home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 23 / AMIGAplus Sonderheft 23 (2000)(Falke)(DE)[!].iso / Updates / Librarys / zee_ini_library / Docs / ini_lib.doc next >
Text File  |  1999-10-30  |  96KB  |  3,699 lines
  1. TABLE OF CONTENTS
  2. 0001 ini.library/--background--
  3. 0002 ini.library/iniAddContext
  4. 0003 ini.library/iniAddContextItem
  5. 0004 ini.library/iniAllocNameStr
  6. 0005 ini.library/iniAllocPMem
  7. 0006 ini.library/iniCheckComment
  8. 0007 ini.library/iniClose
  9. 0008 ini.library/iniCreateContext
  10. 0009 ini.library/iniCreateContextItem
  11. 0010 ini.library/iniDeleteContext
  12. 0011 ini.library/iniDeleteContextItem
  13. 0012 ini.library/iniFindContext
  14. 0013 ini.library/iniFindItem
  15. 0014 ini.library/iniFloatToStr
  16. 0015 ini.library/iniFreeContext
  17. 0016 ini.library/iniFreeContextItem
  18. 0017 ini.library/iniFreeNameStr
  19. 0018 ini.library/iniFreePMem
  20. 0019 ini.library/iniGetArrayLine
  21. 0020 ini.library/iniGetArrayPos
  22. 0021 ini.library/iniGetByteA
  23. 0022 ini.library/iniGetContextItem
  24. 0023 ini.library/iniGetContextItemData
  25. 0024 ini.library/iniGetContextItemDataA
  26. 0025 ini.library/iniGetContextName
  27. 0026 ini.library/iniGetFloat
  28. 0027 ini.library/iniGetFloatA
  29. 0028 ini.library/iniGetLong
  30. 0029 ini.library/iniGetLongA
  31. 0030 ini.library/iniGetNumArrays
  32. 0031 ini.library/iniGetStr
  33. 0032 ini.library/iniGetStrA
  34. 0033 ini.library/iniGetWordA
  35. 0034 ini.library/iniInsertContext
  36. 0035 ini.library/iniInsertContextItem
  37. 0036 ini.library/iniIntToStr
  38. 0037 ini.library/iniOpenDefault
  39. 0038 ini.library/iniOpenFile
  40. 0039 ini.library/iniOpenFromFH
  41. 0040 ini.library/iniOpenMem
  42. 0041 ini.library/iniPutByteA
  43. 0042 ini.library/iniPutFloat
  44. 0043 ini.library/iniPutFloatA
  45. 0044 ini.library/iniPutLong
  46. 0045 ini.library/iniPutLongA
  47. 0046 ini.library/iniPutStr
  48. 0047 ini.library/iniPutStrA
  49. 0048 ini.library/iniPutWordA
  50. 0049 ini.library/iniReadByteA
  51. 0050 ini.library/iniReadFloat
  52. 0051 ini.library/iniReadFloatA
  53. 0052 ini.library/iniReadLong
  54. 0053 ini.library/iniReadLongA
  55. 0054 ini.library/iniReadStr
  56. 0055 ini.library/iniReadStrA
  57. 0056 ini.library/iniReadWordA
  58. 0057 ini.library/iniRemContext
  59. 0058 ini.library/iniRemContextItem
  60. 0059 ini.library/iniSaveFile
  61. 0060 ini.library/iniSaveToFH
  62. 0061 ini.library/iniSetNameStr
  63. 0062 ini.library/iniSetString
  64. 0063 ini.library/iniStrToFloat
  65. 0064 ini.library/iniStrToInt
  66. 0065 ini.library/iniWriteByteA
  67. 0066 ini.library/iniWriteFloat
  68. 0067 ini.library/iniWriteFloatA
  69. 0068 ini.library/iniWriteLong
  70. 0069 ini.library/iniWriteLongA
  71. 0070 ini.library/iniWriteStr
  72. 0071 ini.library/iniWriteStrA
  73. 0072 ini.library/iniWriteWordA
  74. ini.library/--background--
  75.  
  76. PURPOSE
  77.  
  78.        The 'ini.library' was created, because there was no easy way of
  79.        handling configuration files. Each program had it's own format.
  80.  
  81.        This library tries to help you in making a standard file format for
  82.        configuration files. These files are in plain ASCII, so you can use
  83.        your favourite text editor to edit them, and, in addition, of course,
  84.        you can use the prefs section of your program.
  85.  
  86.  
  87. OVERVIEW
  88.  
  89.        The initialization files (INI files) come from Microsoft Windows 3.x.
  90.        They are built up as follows:
  91.        [Context1]
  92.          Item1 = Long1
  93.          Item2 = Long2
  94.          Item3 = LongA1, LongA2, LongA3,
  95.                  LongA4, LongA5, LongA6,
  96.          Item4 = Float1
  97.          Item5 = String1
  98.  
  99.        [Context2]
  100.          Item1 = Float1
  101.        ...
  102.  
  103.        * Easy accessable
  104.  
  105.        The library makes it easy to read/write access those context/item
  106.        fields. You can easily add/remove new items, contexts, etc.
  107.  
  108.        * Comments, etc. are all handled & preserved automatically!
  109.  
  110.        Yes, if you update an INI context item, the comment after the line
  111.        is preserved. That means, if you update the INI file in a program,
  112.        you don't need to have any fears of lossing something.
  113.  
  114.        * Both high- and low-level access functions
  115.   
  116.        You can choose between simply access and complex access. Low level
  117.        functions are for complex access, high level functions are for quick
  118.        and easy access. But the high level functions are a little slower.
  119.  
  120.  
  121.  
  122. ini.library/iniAddContext
  123.  
  124. NAME
  125.        iniAddContext -- adds a new freshly allocated context to an INI file
  126.                         structure
  127.  
  128.  
  129. SYNOPSIS
  130.        iniAddContext( iniFile, ContextStr );
  131.                       A0       A1
  132.  
  133.        void iniAddContext( struct iniFile *, struct iniContext *);
  134.  
  135.  
  136. FUNCTION
  137.        Adds a freshly created context to a specified INI file.
  138.        To add items, you first need to add context items, see there.
  139.  
  140.  
  141. INPUTS
  142.        iniFile - Pointer to INI structure where to add it
  143.        ContextStr - Freshly context structure to add
  144.  
  145.  
  146. EXAMPLE
  147.  
  148.  
  149. NOTES
  150.        You need to call this function to make a *NEW* context available
  151.        to the other functions.
  152.  
  153.  
  154. BUGS
  155.  
  156.  
  157. SEE ALSO
  158.        iniCreateContext(), iniFreeContext(), iniRemContext(),
  159.        iniInsertContext(), iniDeleteContext(), <libraries/ini_lib.h>
  160.  
  161.  
  162. ini.library/iniAddContextItem
  163.  
  164. NAME
  165.        iniAddContextItem -- adds a new freshly allocated context item to
  166.                             an context structure
  167.  
  168.  
  169. SYNOPSIS
  170.        iniAddContextItem( ContextStr, ContextItemLine );
  171.                           A0          A1
  172.  
  173.        void iniAddContextItem( struct iniContext *,
  174.            struct iniContextItemLine *);
  175.  
  176.  
  177. FUNCTION
  178.        Adds a freshly created context item to a specified context.
  179.  
  180.  
  181. INPUTS
  182.        ContextStr - Pointer to context structure where to add it
  183.        ContextItemLine - Freshly context item structure to add
  184.  
  185.  
  186. EXAMPLE
  187.  
  188.  
  189. NOTES
  190.        You need to call this function to make a *NEW* context item available
  191.        to the other functions.
  192.  
  193.  
  194. BUGS
  195.  
  196.  
  197. SEE ALSO
  198.        iniCreateContextItem(), iniFreeContextItem(), iniRemContextItem(),
  199.        iniInsertContextItem(), iniDeleteContextItem(), <libraries/ini_lib.h>
  200.  
  201.  
  202. ini.library/iniAllocNameStr
  203.  
  204. NAME
  205.        iniAllocNameStr -- allocate a name string compatible with the library
  206.  
  207.  
  208. SYNOPSIS
  209.        namestring = iniAllocNameStr( string );
  210.        D0                            A0
  211.  
  212.        STRPTR iniAllocNameStr( STRPTR string );
  213.  
  214.  
  215. FUNCTION
  216.        Allocates a name string out of a standard C-String. This is required
  217.        if you use own strings in the library handlers.
  218.  
  219.  
  220. INPUTS
  221.        string - The string to be allocated. Must be null terminated.
  222.  
  223.  
  224. RESULT
  225.        namestring - The initialized name structure. To deallocate, use
  226.            iniFreeNameStr() on this result.
  227.  
  228.  
  229. EXAMPLE
  230.  
  231.  
  232. NOTES
  233.        The namestring is a copy of string, but it's freed via iniFreePMem()
  234.  
  235.  
  236. BUGS
  237.  
  238.  
  239. SEE ALSO
  240.       iniFreeNameStr(), iniSetNameStr(), iniSetString()
  241.  
  242.  
  243. ini.library/iniAllocPMem
  244.  
  245. NAME
  246.        iniAllocPMem -- allocate MEMF_PUBLIC|MEMF_CLEAR memory like AllocMem()
  247.                        but use memory pools if running under OS3.0+
  248.  
  249.  
  250. SYNOPSIS
  251.        memoryBlock = iniAllocPMem( byteSize );
  252.        D0                          D0
  253.  
  254.        APTR iniAllocPMem( ULONG );
  255.  
  256.  
  257. FUNCTION
  258.        Allocates memory always with MEMF_PUBLIC and MEMF_CLEAR flags set and
  259.        uses, if possible, the OS3.0+ memory pools. I have decided to
  260.        implement this function, because the INI library allocates often
  261.        very small chunks of memory, which is handled more efficiency with
  262.        memory pools.
  263.  
  264.        Each memory pool has a size of 32768 bytes and a threshold of
  265.        4096 bytes.
  266.  
  267.  
  268. INPUTS
  269.        byteSize - number of bytes to allocate. Alignment rules are the
  270.            same as in exec.library/AllocMem() and exec.library/AllocPooled()
  271.  
  272.  
  273. RESULT
  274.        memoryBlock - FALSE if the user cancelled the requester or if something
  275.            prevented the requester from opening. If TRUE, values in the
  276.            requester structure will be set.
  277.  
  278.            If the return value is FALSE, you can look at the result from the
  279.            dos.library/IoErr() function to determine whether the requester
  280.            was cancelled or simply failed to open. If dos.library/IoErr()
  281.            returns 0, then the requester was cancelled, any other value
  282.            indicates a failure to open. Current possible failure codes are
  283.            ERROR_NO_FREE_STORE which indicates there was not enough memory,
  284.            and ERROR_NO_MORE_ENTRIES which indicates no modes were available
  285.            (usually because the application filter hook filtered them all
  286.            away).
  287.  
  288.  
  289. EXAMPLE
  290.  
  291.  
  292. NOTES
  293.        Please note that you MUST deallocate memory allocated with
  294.        iniAllocPMem() with iniFreePMem() or it *MAY* crash!
  295.  
  296.        iniAllocPMem() is used always for internal purposes, so that you
  297.        *MUST* allocate all structures used with this lib with this function.
  298.  
  299.  
  300. BUGS
  301.  
  302.  
  303. SEE ALSO
  304.       iniFreePMem()
  305.  
  306.  
  307. ini.library/iniCheckComment
  308.  
  309. NAME
  310.        iniCheckComment -- Checks if a context line belongs to a comment
  311.  
  312.  
  313. SYNOPSIS
  314.        success = iniCheckComment( ContextStr, ContextItemLine );
  315.        D0                         A0          A1
  316.  
  317.        BOOL iniCheckComment( struct iniContext *,
  318.            struct iniContextItemLine *);
  319.  
  320.  
  321. FUNCTION
  322.        Checks if the given context item line is part of a multiline comment.
  323.        This function is mainly for internal use to easy handle the parsing
  324.        of lines.
  325.  
  326.  
  327. INPUTS
  328.        ContextStr - A pointer to context structure which contains the line
  329.            to be examined.
  330.        ContextItemLine - A pointer to the context item line which should be
  331.            examined.
  332.  
  333.  
  334. RESULT
  335.        success - TRUE if the line is commented else NULL.
  336.  
  337.  
  338. EXAMPLE
  339.  
  340.  
  341. NOTES
  342.  
  343.  
  344. BUGS
  345.  
  346.  
  347. SEE ALSO
  348. <libraries/ini_lib.h>
  349.  
  350.  
  351. ini.library/iniClose
  352.  
  353. NAME
  354.        iniClose -- Deallocate a loaded INI file
  355.  
  356.  
  357. SYNOPSIS
  358.        iniClose( iniFile );
  359.                  A0
  360.  
  361.        void iniClose( struct iniFile *);
  362.  
  363.  
  364. FUNCTION
  365.        This function is used to deallocate the memory required by the
  366.        the loaded INI file. It deallocates everything in the given INI
  367.        file structure.
  368.  
  369.  
  370. INPUTS
  371.        iniFile - A pointer to the INI file structure to be freed
  372.  
  373.  
  374. EXAMPLE
  375.  
  376.  
  377. NOTES
  378.        All memory blocks inside must be allocated using iniAllocPMem() or
  379.        iniAllocNameStr() or it may crash!
  380.  
  381.  
  382. BUGS
  383.  
  384.  
  385. SEE ALSO
  386.        iniOpenFile(), iniOpenFromFH(), iniOpenMem(), <libraries/ini_lib.h>
  387.  
  388.  
  389. ini.library/iniCreateContext
  390.  
  391. NAME
  392.        iniCreateContext -- Creates a new context chunk to be used
  393.  
  394.  
  395. SYNOPSIS
  396.        ContextStr = iniCreateContext( ContextName );
  397.        D0                             A0
  398.  
  399.        struct iniContext *iniCreateContext( STRPTR ContextName );
  400.  
  401.  
  402. FUNCTION
  403.        Creates a new context structure. It can be added with iniAddContext()
  404.        to an INI file structure. The name given mustn't be an AllocNameStr()
  405.        string. Because it's created automatically during the creation
  406.        process..
  407.  
  408.  
  409. INPUTS
  410.        ContextName - The line string of the context
  411.  
  412.  
  413. EXAMPLE
  414.  
  415.  
  416. NOTES
  417.        ContextName is not only the context name itself, but the full line,
  418.        e.g.:
  419.        [ Display ] and not only "Display".
  420.  
  421.  
  422. BUGS
  423.  
  424.  
  425. SEE ALSO
  426.        iniCreateContextItem(), iniFreeContext(), iniAddContext(),
  427.        iniInsertContext(), <libraries/ini_lib.h>
  428.  
  429.  
  430. ini.library/iniCreateContextItem
  431.  
  432. NAME
  433.        iniCreateContextItem -- creates a new context item to be used
  434.  
  435.  
  436. SYNOPSIS
  437.        ContextItemLine = iniCreateContextItem( CStr );
  438.        D0                                      A0
  439.  
  440.        struct iniContextItemLine *iniCreateContextItem( STRPTR CStr );
  441.  
  442.  
  443. FUNCTION
  444.        Creates a new context item line to be used. The string will be used
  445.        as a context line name. Add the result structure to the context
  446.        structure to make it available in the INI file structure.
  447.  
  448.  
  449. INPUTS
  450.        CStr - A null terminated string which will be stored as a
  451.            iniAllocNameStr() string.
  452.  
  453.  
  454. RESULT
  455.        ContextItemLine - The context item structure that can be added to
  456.            the desired context.
  457.  
  458.  
  459. EXAMPLE
  460.  
  461.  
  462. NOTES
  463.  
  464.  
  465. BUGS
  466.  
  467.  
  468. SEE ALSO
  469.       iniCreateContext(), iniFreeContextItem(), iniAddContextItem(),
  470.       iniInsertContextItem(), <libraries/ini_lib.h>
  471.  
  472.  
  473. ini.library/iniDeleteContext
  474.  
  475. NAME
  476.        iniDeleteContext -- deletes a context from an INI file structure
  477.  
  478.  
  479. SYNOPSIS
  480.        iniDeleteContext( ContextStr );
  481.                          A0
  482.  
  483.        void iniDeleteContext( struct iniContext *);
  484.  
  485.  
  486. FUNCTION
  487.        Deletes a context of an INI file and all its associated lines.
  488.        Memory will not be freed. To deallocate, use iniFreeContext()
  489.  
  490.  
  491. INPUTS
  492.        ContextStr - The context structure to be deleted
  493.  
  494.  
  495. RESULT
  496.  
  497.  
  498. EXAMPLE
  499.  
  500.  
  501. NOTES
  502.        Please note that this function removes only the node from the
  503.        INI file structure and doesn't deallocate any memory.
  504.  
  505.  
  506. BUGS
  507.  
  508.  
  509. SEE ALSO
  510.       iniFreeContext(), iniRemContext(), iniInsertContext(),
  511.       <libraries/ini_lib.h>
  512.  
  513.  
  514. ini.library/iniDeleteContextItem
  515.  
  516. NAME
  517.        iniDeleteContextItem -- deletes a context item line from an INI file.
  518.  
  519.  
  520. SYNOPSIS
  521.        iniDeleteContextItem( ContextItemLine );
  522.                              A0
  523.  
  524.        void iniDeleteContextItem( struct iniContextItemLine *);
  525.  
  526.  
  527. FUNCTION
  528.        Deletes a context item line from an INI context. It doesn't
  529.        deallocate any memory, so it can be added otherwise.
  530.  
  531.  
  532. INPUTS
  533.        ContextItemLine - The pointer of the context item line to be deleted.
  534.  
  535.  
  536. RESULT
  537.  
  538.  
  539. EXAMPLE
  540.  
  541.  
  542. NOTES
  543.        Please note that just the node is removed from the context structure
  544.        and there are no deallocation processes. Use iniFreeContextItem()
  545.        for this purpose.
  546.  
  547.  
  548. BUGS
  549.  
  550.  
  551. SEE ALSO
  552.        iniFreeContextItem(), iniRemContextItem(), iniInsertContextItem(),
  553.        <libraries/ini_lib.h>
  554.  
  555. ini.library/iniCreateContext
  556.  
  557. NAME
  558.        iniCreateContext -- Creates a new context chunk to be used
  559.  
  560.  
  561. SYNOPSIS
  562.        ContextStr = iniCreateContext( ContextName );
  563.        D0                             A0
  564.  
  565.        struct iniContext *iniCreateContext( STRPTR ContextName );
  566.  
  567.  
  568. FUNCTION
  569.        Creates a new context structure. It can be added with iniAddContext()
  570.        to an INI file structure. The name given mustn't be an AllocNameStr()
  571.        string. Because it's created automatically during the creation
  572.        process..
  573.  
  574.  
  575. INPUTS
  576.        ContextName - The line string of the context
  577.  
  578.  
  579. EXAMPLE
  580.  
  581.  
  582. NOTES
  583.        ContextName is not only the context name itself, but the full line,
  584.        e.g.:
  585.        [ Display ] and not only "Display".
  586.  
  587.  
  588. BUGS
  589.  
  590.  
  591. SEE ALSO
  592.        iniCreateContextItem(), iniFreeContext(), iniAddContext(),
  593.        iniInsertContext(), <libraries/ini_lib.h>
  594.  
  595.  
  596. ini.library/iniCreateContextItem
  597.  
  598. NAME
  599.        iniCreateContextItem -- creates a new context item to be used
  600.  
  601.  
  602. SYNOPSIS
  603.        ContextItemLine = iniCreateContextItem( CStr );
  604.        D0                                      A0
  605.  
  606.        struct iniContextItemLine *iniCreateContextItem( STRPTR CStr );
  607.  
  608.  
  609. FUNCTION
  610.        Creates a new context item line to be used. The string will be used
  611.        as a context line name. Add the result structure to the context
  612.        structure to make it available in the INI file structure.
  613.  
  614.  
  615. INPUTS
  616.        CStr - A null terminated string which will be stored as a
  617.            iniAllocNameStr() string.
  618.  
  619.  
  620. RESULT
  621.        ContextItemLine - The context item structure that can be added to
  622.            the desired context.
  623.  
  624.  
  625. EXAMPLE
  626.  
  627.  
  628. NOTES
  629.  
  630.  
  631. BUGS
  632.  
  633.  
  634. SEE ALSO
  635.       iniCreateContext(), iniFreeContextItem(), iniAddContextItem(),
  636.       iniInsertContextItem(), <libraries/ini_lib.h>
  637.  
  638.  
  639. ini.library/iniFindContext
  640.  
  641. NAME
  642.        iniFindContext -- Search for a context in an INI file.
  643.  
  644.  
  645. SYNOPSIS
  646.        ContextStr = iniFindContext( iniFile, ContextName, Flags );
  647.        D0                           A0       A1           D0
  648.  
  649.        struct iniContext *iniFindContext( struct iniFile *,
  650.            STRPTR, ULONG );
  651.  
  652.  
  653. FUNCTION
  654.        Searches a loaded INI file for the specified context.
  655.  
  656.  
  657. INPUTS
  658.        iniFile - Pointer to INI structure to search
  659.        ContextName - Name of the context to be searched
  660.        Flags - Search flags. They're currently defined as:
  661.            INIF_ContextCase - Set this flag if the search of the context
  662.                name should be case sensitive.
  663.  
  664.  
  665. RESULT
  666.        ContextStr - The context structure if the context was found else
  667.            NULL.
  668.  
  669.  
  670. EXAMPLE
  671.  
  672.  
  673. NOTES
  674.  
  675.  
  676. BUGS
  677.  
  678.  
  679. SEE ALSO
  680.        iniCreateContext(), iniFindItem(), <libraries/ini_lib.h>
  681.  
  682.  
  683. ini.library/iniFindItem
  684.  
  685. NAME
  686.        iniFindItem -- finds a context item in a specified context
  687.  
  688.  
  689. SYNOPSIS
  690.        ContextItemLine = iniFindItem( ContextStr, ContextItemName, Flags );
  691.        D0                             A0          A1               D0
  692.  
  693.        struct iniContextItemLine *iniFindItem( struct iniContext *,
  694.            STRPTR, ULONG );
  695.  
  696.  
  697. FUNCTION
  698.        Searches for a context item in the specified context
  699.  
  700.  
  701. INPUTS
  702.        ContextStr - Context structure where to search in
  703.        ContextItemName - Name of the context item to be searched
  704.        Flags - Search flags. They're currently defined as:
  705.            INIF_ContextItemCase - Set this flag if the search of the context
  706.                item name should be case sensitive.
  707.  
  708.  
  709. RESULT
  710.        ContextItemLine - The context item structure if the context item
  711.            was found else NULL.
  712.  
  713.  
  714. EXAMPLE
  715.  
  716.  
  717. NOTES
  718.  
  719.  
  720. BUGS
  721.  
  722.  
  723. SEE ALSO
  724.       iniCreateContextItem(), iniFindContext(), <libraries/ini_lib.h>
  725.  
  726.  
  727. ini.library/iniFloatToStr
  728.  
  729. NAME
  730.        iniFloatToStr -- Converts a quick float value to a string.
  731.  
  732.  
  733. SYNOPSIS
  734.        string = iniFloatToStr( Buffer, Float, FltFormat, IntLen, FracLen,
  735.        D0                      A0      D0     D1         D2      D3
  736.                                ZeroSep );
  737.                                D4:8
  738.  
  739.        STRPTR iniFloatToStr( STRPTR, ULONG, ULONG, ULONG, ULONG, UBYTE );
  740.  
  741.  
  742. FUNCTION
  743.        This function is used to convert a quick float value to a standard
  744.        ASCII string. A quick float value has in it's upper 16-bits the
  745.        decimal value and in the lower 16-bits the fraction. That means, the
  746.        highest possible accuracy is 1/65536.
  747.  
  748.  
  749. INPUTS
  750.        Buffer - A pointer to at least a 128 byte buffer or NULL to create a
  751.            new one.
  752.        Float - Quick float value to convert.
  753.        FltFormat - Format of the floating point value. Can be any of:
  754.            INI_FLOAT_FORMAT_DEC - Use decimal with point separator
  755.            INI_FLOAT_UNSIGNED - Add this to indicate unsigned quick float
  756.        IntLen - Forced length of integer part or NULL for no force.
  757.        FracLen - Forced length of fractional part or NULL for no force.
  758.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  759.  
  760.  
  761. RESULT
  762.        string - Pointer to the string where the converted string is stored.
  763.  
  764.  
  765. EXAMPLE
  766.  
  767.  
  768. NOTES
  769.  
  770.  
  771. BUGS
  772.       The buffer is not checked for overflow. That means, IntLen and FracLen
  773.       should not be greater than 90% of your buffer when added together.
  774.  
  775.  
  776. SEE ALSO
  777.       iniStrToFloat(), iniStrToInt(), iniIntToStr(), <libraries/ini_lib.h>
  778.  
  779.  
  780. ini.library/iniFreeContext
  781.  
  782. NAME
  783.        iniFreeContext -- Deletes if necessary and deallocates a context
  784.            structure.
  785.  
  786.  
  787. SYNOPSIS
  788.        iniFreeContext( ContextStr );
  789.                        A0
  790.  
  791.        void iniFreeContext( struct iniContext *);
  792.  
  793.  
  794. FUNCTION
  795.        This function removes first (see iniDeleteContext()), if necessary a
  796.        context structure and then deallocates the memory used by it using
  797.        iniFreePMem() and iniFreeNameStr().
  798.  
  799.  
  800. INPUTS
  801.        ContextStr - A pointer to a context structure to be deallocated.
  802.  
  803.  
  804. RESULT
  805.  
  806.  
  807. EXAMPLE
  808.  
  809.  
  810. NOTES
  811.        The structure MUST be allocated with iniAllocPMem() and the strings
  812.        must be allocated with iniAllocNameStr()
  813.  
  814.  
  815. BUGS
  816.  
  817.  
  818. SEE ALSO
  819.        iniCreateContext(), iniRemContext(), iniDeleteContext(),
  820.        iniFreeContextItem(), <libraries/ini_lib.h>
  821.  
  822.  
  823. ini.library/iniFreeContextItem
  824.  
  825. NAME
  826.        iniFreeContextItem -- Deallocates a context item structure
  827.  
  828.  
  829. SYNOPSIS
  830.        iniFreeContextItem( ContextItemLine );
  831.                            A0
  832.  
  833.        void iniFreeContextItem( struct iniContextItemLine *);
  834.  
  835.  
  836. FUNCTION
  837.        Removes (if necessary) a context item line and deallocates the memory
  838.        required by it afterwards. iniFreePMem() and iniFreeNameStr() are
  839.        used for deallocation.
  840.  
  841.  
  842. INPUTS
  843.        ContextItemLine - Pointer to the context item line to be deallocated.
  844.  
  845.  
  846. RESULT
  847.  
  848.  
  849. EXAMPLE
  850.  
  851.  
  852. NOTES
  853.        The structure MUST be allocated with iniAllocPMem() and the strings
  854.        need to be allocated with iniAllocNameStr().
  855.  
  856.  
  857. BUGS
  858.  
  859.  
  860. SEE ALSO
  861.       iniCreateContextItem(), iniRemContextItem(), iniDeleteContextItem(),
  862.       iniFreeContext(), <libraries/ini_lib.h>
  863.  
  864.  
  865. ini.library/iniFreeNameStr
  866.  
  867. NAME
  868.        iniFreeNameStr -- Deallocate an iniAllocNameStr() name structure.
  869.  
  870.  
  871. SYNOPSIS
  872.        iniFreeNameStr( namestring );
  873.                        A0
  874.  
  875.        void iniFreeNameStr( STRPTR );
  876.  
  877.  
  878. FUNCTION
  879.        Deallocates a name structure, allocated previously by
  880.        iniAllocNameStr()
  881.  
  882.  
  883. INPUTS
  884.        namestring - A pointer to a previously allocated name string. The
  885.            size of deallocation is calculated automatically.
  886.  
  887.  
  888. RESULT
  889.  
  890.  
  891. EXAMPLE
  892.  
  893.  
  894. NOTES
  895.        Please deallocate ONLY those things allocated with iniAllocNameStr()
  896.        with this function, since the allocation mechanism may change at any
  897.        time!
  898.  
  899.  
  900. BUGS
  901.  
  902.  
  903. SEE ALSO
  904.        iniAllocNameStr(), iniAllocPMem(), iniFreePMem()
  905.  
  906.  
  907. ini.library/iniFreePMem
  908.  
  909. NAME
  910.        iniFreePMem -- deallocates memory allocated by iniAllocPMem()
  911.  
  912.  
  913. SYNOPSIS
  914.        iniFreePMem( memoryBlock, byteSize)
  915.                     A1           D0
  916.  
  917.        void iniFreePMem( APTR, ULONG );
  918.  
  919.  
  920. FUNCTION
  921.        Deallocates any memory allocated by iniFreePMem(), it works just like
  922.        the exec.library/FreeMem function.
  923.  
  924.  
  925. INPUTS
  926.        memoryBlock - The block that should be deallocated
  927.        byteSize - Number of bytes to be deallocated. It is aligned
  928.            automatically.
  929.  
  930.  
  931. RESULT
  932.  
  933.  
  934. EXAMPLE
  935.  
  936.  
  937. NOTES
  938.        Please use this function to deallocate ONLY iniAllocPMem() blocks,
  939.        if you don't do this, the system may crash within OS3.0+, since the
  940.        function uses memory pools in that case.
  941.  
  942.  
  943. BUGS
  944.  
  945.  
  946. SEE ALSO
  947.        iniAllocPMem()
  948.  
  949.  
  950. ini.library/iniGetArrayLine
  951.  
  952. NAME
  953.        iniGetArrayLine -- Returns the array line of the context item number
  954.  
  955.  
  956. SYNOPSIS
  957.        ContextItemPos = iniGetArrayLine( ContextStr, ContextItemLine,
  958.        D0                                A0          A1
  959.                                          Number );
  960.                                          D0
  961.  
  962.        struct iniContextItemLine *iniGetArrayLine( struct iniContext *,
  963.                              struct iniContextItemLine *, ULONG );
  964.  
  965.  
  966. FUNCTION
  967.        Gets the context item line structure of the given context item's nth
  968.        array (nth is the Number given in D0)
  969.  
  970.  
  971. INPUTS
  972.        ContextStr - Context structure where context item is
  973.        ContextItemLine - Context item line where's array's first entry.
  974.        Number - Array number of which the line address should be returned.
  975.  
  976.  
  977. RESULT
  978.        ContextItemLine - Context item line address of the number given.
  979.  
  980.  
  981. EXAMPLE
  982.  
  983.  
  984. NOTES
  985.        This function is mainly only for internal purposes. It allows
  986.        array handling faster.
  987.  
  988.  
  989. BUGS
  990.  
  991.  
  992. SEE ALSO
  993.        iniGetNumArrays(), iniGetArrayPos(), <libraries/ini_lib.h>
  994.  
  995.  
  996. ini.library/iniGetArrayPos
  997.  
  998. NAME
  999.        iniGetArrayPos -- Returns the position of the context item number.
  1000.  
  1001.  
  1002. SYNOPSIS
  1003.        ContextItemPos = iniGetArrayPos( ContextStr, ContextItemLine,
  1004.        D0                               A0          A1
  1005.                                         Number );
  1006.                                         D0
  1007.  
  1008.        struct iniContextItemLine *iniGetArrayPos( struct iniContext *,
  1009.                              struct iniContextItemLine *, ULONG );
  1010.  
  1011.  
  1012. FUNCTION
  1013.        Gets the line position of the given context item's nth array
  1014.        (nth is the Number given in D0)
  1015.  
  1016.  
  1017. INPUTS
  1018.        ContextStr - Context structure where context item is
  1019.        ContextItemLine - Context item line where's array's first entry.
  1020.        Number - Array number of which the line position should be returned.
  1021.  
  1022.  
  1023. RESULT
  1024.        ContextItemLine - Context item line address of the number given.
  1025.  
  1026.  
  1027. EXAMPLE
  1028.  
  1029.  
  1030. NOTES
  1031.        This function is mainly only for internal purposes. It allows
  1032.        easy array access.
  1033.  
  1034.  
  1035. BUGS
  1036.  
  1037.  
  1038. SEE ALSO
  1039.        iniGetNumArrays(), iniGetArrayLine(), <libraries/ini_lib.h>
  1040.  
  1041.  
  1042. ini.library/iniGetByteA
  1043.  
  1044. NAME
  1045.        iniGetByteA -- reads a context item array into a (U)BYTE array.
  1046.  
  1047.  
  1048. SYNOPSIS
  1049.        success = iniGetByteA( ContextStr, ContextItemLine, Array, Entries );
  1050.        D0                     A0          A1               A2     D0
  1051.  
  1052.        BOOL iniGetByteA( struct iniContext *, struct iniContextItemLine *,
  1053.            BYTE *, ULONG );
  1054.  
  1055.  
  1056. FUNCTION
  1057.        Reads a context item array and stores the read bytes into a
  1058.        (U)BYTE table you specified.
  1059.  
  1060.  
  1061. INPUTS
  1062.        ContextStr - The context structure where the context line is in
  1063.        ContextItemLine - The context item line where the array is
  1064.        Array - An (U)BYTE array where to store the values
  1065.        Entries - Number of entries to read (further entries will be ignored)
  1066.  
  1067.  
  1068. RESULT
  1069.        success - TRUE if line could be evaluated else FALSE
  1070.  
  1071.  
  1072. EXAMPLE
  1073.  
  1074.  
  1075. NOTES
  1076.        Make sure that the given array is big enough to hold all values or
  1077.        some memory area may be overwritten.
  1078.  
  1079.        Fields which can't be evaluated are left unchanged.
  1080.  
  1081.  
  1082. BUGS
  1083.  
  1084.  
  1085. SEE ALSO
  1086.        iniGetWordA(), iniGetLongA(), iniReadByteA(), iniPutByteA(),
  1087.        <libraries/ini_lib.h>
  1088.  
  1089.  
  1090. ini.library/iniGetContextItem
  1091.  
  1092. NAME
  1093.        iniGetContextItem -- Gets the name of the context item
  1094.  
  1095.  
  1096. SYNOPSIS
  1097.        Buffer = iniGetContextItem( ContextStr, ContextItemLine, Buffer );
  1098.        D0                          A0          A1               A2
  1099.  
  1100.        STRPTR iniGetContextItem( struct iniContext *,
  1101.            struct iniContextItemLine *, STRPTR );
  1102.  
  1103.  
  1104. FUNCTION
  1105.        Gets the context item name of the context item line given
  1106.  
  1107.  
  1108. INPUTS
  1109.        ContextStr - Context structure where context item lies
  1110.        ContextItemLine - Pointer to context item line structure
  1111.        Buffer - Optional buffer where to store name or NULL to create new
  1112.  
  1113.  
  1114. RESULT
  1115.        Buffer - STRPTR to newly created buffer if none was specified or NULL
  1116.            on error. If existing buffer was given, it will be returned
  1117.            instead.
  1118.  
  1119.  
  1120. EXAMPLE
  1121.  
  1122.  
  1123. NOTES
  1124.        This function is called by all functions which evaluate INI file
  1125.        context item data. It is, in fact, a low level function. The given
  1126.        buffer must have a mininum size of 128 bytes.
  1127.        If no buffer is given, the new one must be freed with iniFreeNameStr()
  1128.  
  1129.  
  1130. BUGS
  1131.  
  1132.  
  1133. SEE ALSO
  1134.        iniGetContextName(), iniGetContextItemData(),
  1135.        iniGetContextItemDataA(), <libraries/ini_lib.h>
  1136.  
  1137.  
  1138. ini.library/iniGetContextItemData
  1139.  
  1140. NAME
  1141.        iniGetContextItemData -- Gets the data of the context item
  1142.  
  1143.  
  1144. SYNOPSIS
  1145.        Buffer = iniGetContextItemData( ContextStr, ContextItemLine, Buffer );
  1146.        D0                              A0          A1               A2
  1147.  
  1148.        STRPTR iniGetContextItemData( struct iniContext *,
  1149.            struct iniContextItemLine *, STRPTR );
  1150.  
  1151.  
  1152. FUNCTION
  1153.        Gets the context item data of the context item line given
  1154.  
  1155.  
  1156. INPUTS
  1157.        ContextStr - Context structure where context item data lies
  1158.        ContextItemLine - Pointer to context item line structure
  1159.        Buffer - Optional buffer where to store data or NULL to create new
  1160.  
  1161.  
  1162. RESULT
  1163.        Buffer - STRPTR to newly created buffer if none was specified or NULL
  1164.            on error. If existing buffer was given, it will be returned
  1165.            instead.
  1166.  
  1167.  
  1168. EXAMPLE
  1169.  
  1170.  
  1171. NOTES
  1172.        This function is called by all functions which evaluate INI file
  1173.        context item data. It is, in fact, a low level function. The given
  1174.        buffer must have a mininum size of 128 bytes.
  1175.        If no buffer is given, the new one must be freed with iniFreeNameStr()
  1176.  
  1177.  
  1178. BUGS
  1179.  
  1180.  
  1181. SEE ALSO
  1182.        iniGetContextName(), iniGetContextItem(), iniContextItemDataA(),
  1183.        <libraries/ini_lib.h>
  1184.  
  1185.  
  1186. ini.library/iniGetContextItemDataA
  1187.  
  1188. NAME
  1189.        iniGetContextItemDataA -- Gets the data of the context item array
  1190.  
  1191.  
  1192. SYNOPSIS
  1193.        Buffer = iniGetContextItemDataA( ContextStr, ContextItemLine,
  1194.        D0                               A0          A1
  1195.                                         Buffer, Number );
  1196.                                         A2      D0
  1197.  
  1198.        STRPTR iniGetContextItemDataA( struct iniContext *,
  1199.            struct iniContextItemLine *, STRPTR, ULONG );
  1200.  
  1201.  
  1202. FUNCTION
  1203.        Gets the context item array data of the context item line given
  1204.  
  1205.  
  1206. INPUTS
  1207.        ContextStr - Context structure where context item array lies
  1208.        ContextItemLine - Pointer to context item line structure
  1209.        Buffer - Optional buffer where to store data or NULL to create new
  1210.        Number - The entry which should be extracted out of the array. NULL
  1211.            is the first one
  1212.  
  1213.  
  1214. RESULT
  1215.        Buffer - STRPTR to newly created buffer if none was specified or NULL
  1216.            on error. If existing buffer was given, it will be returned
  1217.            instead.
  1218.  
  1219.  
  1220. EXAMPLE
  1221.  
  1222.  
  1223. NOTES
  1224.        This function is called by all functions which evaluate INI file
  1225.        context item array data. It is, in fact, a low level function. The
  1226.        given buffer must have a mininum size of 128 bytes.
  1227.        If no buffer is given, the new one must be freed with iniFreeNameStr()
  1228.  
  1229.  
  1230. BUGS
  1231.  
  1232.  
  1233. SEE ALSO
  1234.        iniGetContextName(), iniGetContextItem(), iniGetContextItemData(),
  1235.        <libraries/ini_lib.h>
  1236.  
  1237.  
  1238. ini.library/iniGetContextName
  1239.  
  1240. NAME
  1241.        iniGetContextName - Gets the name of the context
  1242.  
  1243.  
  1244. SYNOPSIS
  1245.        Buffer = iniGetContextName( ContextLine, Buffer );
  1246.        D0                          A0           A1
  1247.  
  1248.        STRPTR iniGetContextName( STRPTR, STRPTR );
  1249.  
  1250.  
  1251. FUNCTION
  1252.        Gets the context name of the context line given
  1253.  
  1254.  
  1255. INPUTS
  1256.        ContextStr - Context structure where context line lies
  1257.        Buffer - Optional buffer where to store name or NULL to create new
  1258.  
  1259.  
  1260. RESULT
  1261.        Buffer - STRPTR to newly created buffer if none was specified or NULL
  1262.            on error. If existing buffer was given, it will be returned
  1263.            instead.
  1264.  
  1265.  
  1266. EXAMPLE
  1267.  
  1268.  
  1269. NOTES
  1270.        This function is called by all functions which evaluate INI file
  1271.        context names. It is, in fact, a low level function. The given
  1272.        buffer must have a mininum size of 128 bytes.
  1273.        If no buffer is given, the new one must be freed with iniFreeNameStr()
  1274.  
  1275.  
  1276. BUGS
  1277.  
  1278.  
  1279. SEE ALSO
  1280.        iniGetContextItem(), iniGetContextItemData(),
  1281.        iniGetContextItemDataA(), <libraries/ini_lib.h>
  1282.  
  1283.  
  1284. ini.library/iniGetFloat
  1285.  
  1286. NAME
  1287.        iniGetFloat -- Gets a quick floating point value
  1288.  
  1289.  
  1290. SYNOPSIS
  1291.        QFloatValue = iniGetFloat( ContextStr, ContextItemLine, Default );
  1292.        D0                         A0          A1               D0
  1293.  
  1294.        LONG iniGetFloat( struct iniContext *, struct iniContextItemLine *,
  1295.            LONG );
  1296.  
  1297.  
  1298. FUNCTION
  1299.        Reads a quick float value out of the given context item line
  1300.  
  1301.  
  1302. INPUTS
  1303.        ContextStr - Context structure where quick float value lies in
  1304.        ContextItemLine - Context item line where to extract quick float
  1305.        Default - Default value to take if it can't be evaluated
  1306.  
  1307.  
  1308. RESULT
  1309.        QFloatValue - The quick float value extracted out of the context item
  1310.            line
  1311.  
  1312.  
  1313. EXAMPLE
  1314.  
  1315.  
  1316. NOTES
  1317.        This function is called from iniReadFloat().
  1318.        Only the first four fractional digits are evaluated. However, the
  1319.        5th digit is evaluated for rounding purposes.
  1320.  
  1321.  
  1322. BUGS
  1323.  
  1324.  
  1325. SEE ALSO
  1326.        iniGetLong(), iniGetStr(), iniGetFloatA(), iniPutFloat(),
  1327.        iniReadFloat(), iniWriteFloat(), <libraries/ini_lib.h>
  1328.  
  1329.  
  1330. ini.library/iniGetFloatA
  1331.  
  1332. NAME
  1333.        iniGetFloatA -- Gets quick floating point value(s) out of an array
  1334.  
  1335.  
  1336. SYNOPSIS
  1337.        success = iniGetFloatA( ContextStr, ContextItemLine, Array, Entries );
  1338.        D0                      A0          A1               A2     D0
  1339.  
  1340.        BOOL iniGetFloatA( struct iniContext *, struct iniContextItemLine *,
  1341.            LONG *, ULONG );
  1342.  
  1343.  
  1344. FUNCTION
  1345.        Reads one or more quick float value(s) out of the given context item
  1346.        line
  1347.  
  1348.  
  1349. INPUTS
  1350.        ContextStr - Context structure where quick float values lie in
  1351.        ContextItemLine - Context item line where to extract quick floats
  1352.        Array - The array where to store the quick float values
  1353.        Entries - Number of array entries. If the array in the INI file is
  1354.             bigger, the remaining entries will be ignored.
  1355.  
  1356.  
  1357. RESULT
  1358.        success - TRUE if accessing was successful else NULL.
  1359.  
  1360.  
  1361. EXAMPLE
  1362.  
  1363.  
  1364. NOTES
  1365.        This function is called from iniReadFloatA().
  1366.        Only the first four fractional digits are evaluated. However, the
  1367.        5th digit is evaluated for rounding purposes.
  1368.        Array fields which can't be evaluated (e.g. bad syntax) are left
  1369.        unchanged. So it's good to fill the array with default values first.
  1370.  
  1371.  
  1372. BUGS
  1373.  
  1374.  
  1375. SEE ALSO
  1376.        iniGetLongA(), iniGetStrA(), iniGetFloat(), iniPutFloatA(),
  1377.        iniReadFloatA(), iniWriteFloatA(), <libraries/ini_lib.h>
  1378.  
  1379.  
  1380. ini.library/iniGetLong
  1381.  
  1382. NAME
  1383.        iniGetLong -- Gets a long integer value
  1384.  
  1385.  
  1386. SYNOPSIS
  1387.        LongValue = iniGetLong( ContextStr, ContextItemLine, Default );
  1388.        D0                      A0          A1               D0
  1389.  
  1390.        LONG iniGetLong( struct iniContext *, struct iniContextItemLine *,
  1391.            LONG );
  1392.  
  1393.  
  1394. FUNCTION
  1395.        Reads a long integer value out of the given context item line
  1396.  
  1397.  
  1398. INPUTS
  1399.        ContextStr - Context structure where long integer value lies in
  1400.        ContextItemLine - Context item line where to extract long integer
  1401.        Default - Default value to take if it can't be evaluated
  1402.  
  1403.  
  1404. RESULT
  1405.        LongValue - The long integer value extracted out of the context item
  1406.            line
  1407.  
  1408.  
  1409. EXAMPLE
  1410.  
  1411.  
  1412. NOTES
  1413.        This function is called from iniReadLong().
  1414.  
  1415.  
  1416. BUGS
  1417.  
  1418.  
  1419. SEE ALSO
  1420.        iniGetFloat(), iniGetStr(), iniGetLongA(), iniPutLong(),
  1421.        iniReadLong(), iniWriteLong(), <libraries/ini_lib.h>
  1422.  
  1423.  
  1424. ini.library/iniGetLongA
  1425.  
  1426. NAME
  1427.        iniGetLongA -- Gets long integer value(s) out of an array
  1428.  
  1429.  
  1430. SYNOPSIS
  1431.        success = iniGetLongA( ContextStr, ContextItemLine, Array, Entries );
  1432.        D0                     A0          A1               A2     D0
  1433.  
  1434.        BOOL iniGetLongA( struct iniContext *, struct iniContextItemLine *,
  1435.            LONG *, ULONG );
  1436.  
  1437.  
  1438. FUNCTION
  1439.        Reads one or more long integer value(s) out of the given context item
  1440.        line
  1441.  
  1442.  
  1443. INPUTS
  1444.        ContextStr - Context structure where long integer values lie in
  1445.        ContextItemLine - Context item line where to extract long integers
  1446.        Array - The array where to store the long integer values
  1447.        Entries - Number of array entries. If the array in the INI file is
  1448.             bigger, the remaining entries will be ignored.
  1449.  
  1450.  
  1451. RESULT
  1452.        success - TRUE if accessing was successful else NULL.
  1453.  
  1454.  
  1455. EXAMPLE
  1456.  
  1457.  
  1458. NOTES
  1459.        This function is called from iniReadLongA().
  1460.        Array fields which can't be evaluated (e.g. bad syntax) are left
  1461.        unchanged. So it's good to fill the array with default values first.
  1462.  
  1463.  
  1464. BUGS
  1465.  
  1466.  
  1467. SEE ALSO
  1468.        iniGetFloatA(), iniGetStrA(), iniGetLong(), iniPutLongA(),
  1469.        iniReadLongA(), iniWriteLongA(), <libraries/ini_lib.h>
  1470.  
  1471.  
  1472. ini.library/iniGetNumArrays
  1473.  
  1474. NAME
  1475.        iniGetNumArrays -- Gets the amount of array fields
  1476.  
  1477.  
  1478. SYNOPSIS
  1479.        Arrays = iniGetNumArrays( ContextStr, ContextItemLine );
  1480.        D0                        A0          A1
  1481.  
  1482.        ULONG iniGetNumArrays( struct iniContext *,
  1483.            struct iniContextItemLine *);
  1484.  
  1485.  
  1486. FUNCTION
  1487.        Returns the amount of array entries in the given context item array.
  1488.  
  1489.  
  1490. INPUTS
  1491.        ContextStr - Context structure where array lies in
  1492.        ContextItemLine - Context item line structure where array starts
  1493.  
  1494.  
  1495. RESULT
  1496.        Arrays - Number of arrays in the given context item line
  1497.  
  1498. EXAMPLE
  1499.  
  1500.  
  1501. NOTES
  1502.        This function usually is used for dynamic array fields.
  1503.        If an error occurs during evaluation, NULL is returned.
  1504.  
  1505.  
  1506. BUGS
  1507.  
  1508.  
  1509. SEE ALSO
  1510.        iniGetLongA(), iniGetWordA(), iniGetByteA(), iniGetFloatA(),
  1511.        iniGetStrA(), <libraries/ini_lib.h>
  1512.  
  1513.  
  1514. ini.library/iniGetStr
  1515.  
  1516. NAME
  1517.        iniGetStr -- Gets a string
  1518.  
  1519.  
  1520. SYNOPSIS
  1521.        String = iniGetStr( ContextStr, ContextItemLine, Default );
  1522.        D0                  A0          A1               A2
  1523.  
  1524.        STRPTR iniGetStr( struct iniContext *, struct iniContextItemLine *,
  1525.            STRPTR );
  1526.  
  1527. FUNCTION
  1528.        Reads a string out of the given context item line
  1529.  
  1530.  
  1531. INPUTS
  1532.        ContextStr - Context structure where string lies in
  1533.        ContextItemLine - Context item line where to extract string
  1534.        Default - Default value to take if it can't be evaluated
  1535.  
  1536.  
  1537. RESULT
  1538.        String - The string extracted out of the context item line
  1539.  
  1540.  
  1541. EXAMPLE
  1542.  
  1543.  
  1544. NOTES
  1545.        This function is called from iniReadStr().
  1546.        This function calls iniGetContextItemData() with no buffer, this
  1547.        means that the string returned must be deallocated with
  1548.        iniFreeNameStr()
  1549.  
  1550.  
  1551. BUGS
  1552.  
  1553.  
  1554. SEE ALSO
  1555.        iniGetContextItemData(), iniGetLongA(), iniGetFloatA(), iniGetStr(),
  1556.        iniPutStr(), iniReadStrA(), iniWriteStrA(), <libraries/ini_lib.h>
  1557.  
  1558.  
  1559. ini.library/iniGetStrA
  1560.  
  1561. NAME
  1562.        iniGetStrA -- Extracts strings out of an array
  1563.  
  1564.  
  1565. SYNOPSIS
  1566.        success = iniGetStrA( ContextStr, ContextItemLine, Array, Entries );
  1567.        D0                    A0          A1               A2     D0
  1568.  
  1569.        BOOL iniGetStrA( struct iniContext *, struct iniContextItemLine *,
  1570.            STRPTR *, ULONG );
  1571.  
  1572.  
  1573. FUNCTION
  1574.        Reads one or more strings out of the given context item line
  1575.  
  1576.  
  1577. INPUTS
  1578.        ContextStr - Context structure where string values lie in
  1579.        ContextItemLine - Context item line where to extract strings
  1580.        Array - The array where to store the pointers to the strings
  1581.        Entries - Number of array entries. If the array in the INI file is
  1582.             bigger, the remaining entries will be ignored.
  1583.  
  1584.  
  1585. RESULT
  1586.        success - TRUE if accessing was successful else NULL.
  1587.  
  1588.  
  1589. EXAMPLE
  1590.  
  1591.  
  1592. NOTES
  1593.        This function is called from iniReadStrA().
  1594.        This function calls iniGetContextItemData() with no buffer.
  1595.        Array fields which can't be evaluated (e.g. bad syntax) are left
  1596.        unchanged. So it's good to fill the array with default strings first.
  1597.        All entries of the array must be deallocated with iniFreeNameStr()
  1598.        when the strings are no longer of use. This means that the default
  1599.        entries of the array must be iniAllocNameStr() strings!
  1600.  
  1601.  
  1602. BUGS
  1603.  
  1604.  
  1605. SEE ALSO
  1606.        iniGetLongA(), iniGetFloatA(), iniGetStr(), iniPutStrA(),
  1607.        iniReadStrA(), iniWriteStrA(), <libraries/ini_lib.h>
  1608.  
  1609.  
  1610. ini.library/iniGetWordA
  1611.  
  1612. NAME
  1613.        iniGetWordA -- reads a context item array into a (U)WORD array.
  1614.  
  1615.  
  1616. SYNOPSIS
  1617.        success = iniGetWordA( ContextStr, ContextItemLine, Array, Entries );
  1618.        D0                     A0          A1               A2     D0
  1619.  
  1620.        BOOL iniGetWordA( struct iniContext *, struct iniContextItemLine *,
  1621.            WORD *, ULONG );
  1622.  
  1623.  
  1624. FUNCTION
  1625.        Reads a context item array and stores the read words into a
  1626.        (U)WORD table you specified.
  1627.  
  1628.  
  1629. INPUTS
  1630.        ContextStr - The context structure where the context line is in
  1631.        ContextItemLine - The context item line where the array is
  1632.        Array - An (U)WORD array where to store the values
  1633.        Entries - Number of entries to read (further entries will be ignored)
  1634.  
  1635.  
  1636. RESULT
  1637.        success - TRUE if line could be evaluated else FALSE
  1638.  
  1639.  
  1640. EXAMPLE
  1641.  
  1642.  
  1643. NOTES
  1644.        Make sure that the given array is big enough to hold all values or
  1645.        some memory area may be overwritten.
  1646.  
  1647.        Fields which can't be evaluated are left unchanged.
  1648.  
  1649.  
  1650. BUGS
  1651.  
  1652.  
  1653. SEE ALSO
  1654.        iniGetByteA(), iniGetLongA(), iniReadWordA(), iniPutWordA(),
  1655.        <libraries/ini_lib.h>
  1656.  
  1657.  
  1658. ini.library/iniInsertContext
  1659.  
  1660. NAME
  1661.        iniInsertContext -- inserts a context in an INI file structure
  1662.  
  1663.  
  1664. SYNOPSIS
  1665.        iniInsertContext( iniFile, ContextStr, PredContext );
  1666.                          A0       A1          A2
  1667.  
  1668.        void iniInsertContext( struct iniFile *, struct iniContext *,
  1669.            struct iniContext *);
  1670.  
  1671.  
  1672. FUNCTION
  1673.        Inserts a context in an INI file and all its associated lines.
  1674.  
  1675.  
  1676. INPUTS
  1677.        iniFile - INI file structure where to insert context structure
  1678.        ContextStr - The context structure to be inserted
  1679.        PredContext - Context structure of the structure where to insert it
  1680.  
  1681.  
  1682. RESULT
  1683.  
  1684.  
  1685. EXAMPLE
  1686.  
  1687.  
  1688. NOTES
  1689.  
  1690.  
  1691. BUGS
  1692.  
  1693.  
  1694. SEE ALSO
  1695.       iniFreeContext(), iniRemContext(), iniDeleteContext(),
  1696.       <libraries/ini_lib.h>
  1697.  
  1698.  
  1699. ini.library/iniInsertContextItem
  1700.  
  1701. NAME
  1702.        iniInsertContextItem -- inserts a context item line in an INI file.
  1703.  
  1704.  
  1705. SYNOPSIS
  1706.        iniInsertContextItem( ContextStr, ContextItemLine, PredLine );
  1707.                              A0          A1               A2
  1708.  
  1709.        void iniInsertContextItem( struct iniContext *,
  1710.            struct iniContextItemLine *, struct iniContextItemLine *);
  1711.  
  1712.  
  1713. FUNCTION
  1714.        Inserts a context item line in an INI context.
  1715.  
  1716.  
  1717. INPUTS
  1718.        ContextStr - The pointer of the context structure where to insert item
  1719.        ContextItemLine - The pointer of the context item line to be inserted.
  1720.        PredLine - The context item line where to insert it.
  1721.  
  1722.  
  1723. RESULT
  1724.  
  1725.  
  1726. EXAMPLE
  1727.  
  1728.  
  1729. NOTES
  1730.  
  1731.  
  1732. BUGS
  1733.  
  1734.  
  1735. SEE ALSO
  1736.        iniFreeContextItem(), iniRemContextItem(), iniDeleteContextItem(),
  1737.        <libraries/ini_lib.h>
  1738.  
  1739. ini.library/iniIntToStr
  1740.  
  1741. NAME
  1742.        iniIntToStr -- Converts an integer value to a string.
  1743.  
  1744.  
  1745. SYNOPSIS
  1746.        string = iniIntToStr( Buffer, Integer, Format, Len, ZeroSep );
  1747.        D0                    A0      D0       D1      D2   D3:8
  1748.  
  1749.        STRPTR iniIntToStr( STRPTR, ULONG, ULONG, ULONG, UBYTE );
  1750.  
  1751.  
  1752. FUNCTION
  1753.        This function is used to convert an integer value to a standard
  1754.        ASCII string.
  1755.  
  1756.  
  1757. INPUTS
  1758.        Buffer - A pointer to a buffer or NULL to create a new one.
  1759.            The buffer must be large enough to hold all values.
  1760.        Integer - Integer value to convert.
  1761.        Format - Format of the outputted string. Can be any of:
  1762.            INI_FORMAT_DEC - Use decimal with no precedor
  1763.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  1764.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  1765.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  1766.            INI_FORMAT_BIN - Use binary with % precedor
  1767.            INI_FORMAT_OCT - Use octal with & precedor
  1768.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  1769.            INI_FORMAT_YN - Use N for zero, Y for all others
  1770.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  1771.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  1772.            INI_UNSIGNED - Add this to indicate unsigned integer
  1773.        Len - Forced length of outputted string or NULL for no force.
  1774.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  1775.  
  1776.  
  1777. RESULT
  1778.        string - Pointer to the string where the converted string is stored.
  1779.  
  1780.  
  1781. EXAMPLE
  1782.  
  1783.  
  1784. NOTES
  1785.  
  1786.  
  1787. BUGS
  1788.       The buffer is not checked for overflow. That means, IntLen should
  1789.       should be lesser than your buffer.
  1790.  
  1791.  
  1792. SEE ALSO
  1793.       iniStrToInt(), iniStrToFloat(), iniFloatToStr(), <libraries/ini_lib.h>
  1794.  
  1795.  
  1796. ini.library/iniOpenDefault
  1797.  
  1798. NAME
  1799.        iniOpenDefault -- Opens INI file for read access
  1800.  
  1801.  
  1802. SYNOPSIS
  1803.        iniFile = iniOpenDefault( address, name, len );
  1804.        D0                        A0       A1    D0
  1805.  
  1806.        struct iniFile *iniOpenDefault( APTR, STRPTR name, ULONG );
  1807.  
  1808.  
  1809. FUNCTION
  1810.        Opens an INI file for read access and creates a iniFile structure
  1811.        for it. If the file doesn't exist, a default file will be created.
  1812.  
  1813.  
  1814. INPUTS
  1815.        address - Address where default INI file lies (in memory)
  1816.        name - File name of the INI file to be accessed
  1817.        len - Length of the default INI file
  1818.  
  1819.  
  1820. RESULT
  1821.        iniFile - A valid INI file structure ready to be evaluated.
  1822.  
  1823.  
  1824. EXAMPLE
  1825.  
  1826.  
  1827. NOTES
  1828.        The default file will only be created, if the Open() fails with
  1829.        an ERROR_OBJECT_NOT_FOUND (code 205) error.
  1830.        If the default file can't be created (disk full, etc.) the function
  1831.        will use the default file in memory.
  1832.  
  1833.  
  1834. BUGS
  1835.  
  1836.  
  1837. SEE ALSO
  1838.        iniOpenFile(), iniOpenMem(), iniClose(), iniSaveFile(),
  1839.        <libraries/ini_lib.h>
  1840.  
  1841.  
  1842. ini.library/iniOpenFile
  1843.  
  1844. NAME
  1845.        iniOpenFile -- Prepares an INI file for context access
  1846.  
  1847.  
  1848. SYNOPSIS
  1849.        iniFile = iniOpenFile( name, accessMode );
  1850.        D0                     D1    D2
  1851.  
  1852.        struct iniFile *iniOpenFile( STRPTR name, LONG );
  1853.  
  1854.  
  1855. FUNCTION
  1856.        Opens an INI file for read access and prepares an iniFile structure
  1857.        for evaluation. After this the INI file contents can be evaluated
  1858.  
  1859.  
  1860. INPUTS
  1861.        name - Name of the INI file to be opened.
  1862.        accessMode - Read mode of file (see <libraries/dos.h> for details)
  1863.  
  1864.  
  1865. RESULT
  1866.        iniFile - An INI file structure which is ready for evaluation
  1867.  
  1868.  
  1869. EXAMPLE
  1870.  
  1871.  
  1872. NOTES
  1873.  
  1874.  
  1875. BUGS
  1876.  
  1877.  
  1878. SEE ALSO
  1879.        iniOpenDefault(), iniOpenFromFH(), iniOpenMem(), iniClose(),
  1880.        iniSaveFile(), <libraries/ini_lib.h>, <libraries/dos.h>
  1881.  
  1882.  
  1883. ini.library/iniOpenFromFH
  1884.  
  1885. NAME
  1886.        iniOpenFromFH -- initializes an INI file from an already open file
  1887.  
  1888.  
  1889. SYNOPSIS
  1890.        iniFile = iniOpenFromFH( fh, len );
  1891.        D0                       D1  D2
  1892.  
  1893.        struct iniFile *iniOpenFromFH( BPTR, ULONG );
  1894.  
  1895.  
  1896. FUNCTION
  1897.        Reads the INI data from an already open file and initializes the
  1898.        iniFile structure.
  1899.  
  1900.  
  1901. INPUTS
  1902.        fh - BPTR to an file handle of the already opened file to be read.
  1903.        len - Length of file (or length of bytes to read at maximum)
  1904.  
  1905.  
  1906. RESULT
  1907.        iniFile - An initialized INI file structure ready for evaluation
  1908.  
  1909.  
  1910. EXAMPLE
  1911.  
  1912.  
  1913. NOTES
  1914.  
  1915.  
  1916. BUGS
  1917.  
  1918.  
  1919. SEE ALSO
  1920.        iniOpenDefault(), iniOpenFile(), iniOpenMem(), iniClose(),
  1921.        iniSaveFile(), iniSaveToFH(), <libraries/ini_lib.h>
  1922.  
  1923.  
  1924. ini.library/iniOpenMem
  1925.  
  1926. NAME
  1927.        iniOpenMem -- Initializes a INI file structure from an INI file
  1928.            already in memory.
  1929.  
  1930.  
  1931. SYNOPSIS
  1932.        iniFile = iniOpenMem( address, len );
  1933.        D0                    A0       D0
  1934.  
  1935.        struct iniFile *iniOpenMem( APTR, ULONG );
  1936.  
  1937.  
  1938. FUNCTION
  1939.        Initializes an INI file structure from an INI file already in
  1940.        memory.
  1941.  
  1942.  
  1943. INPUTS
  1944.        address - Address where the INI file lies
  1945.        len - Length of INI file in memory
  1946.  
  1947.  
  1948. RESULT
  1949.        iniFile - Valid initialized INI file structure ready to be evaluated
  1950.  
  1951.  
  1952. EXAMPLE
  1953.  
  1954.  
  1955. NOTES
  1956.  
  1957.  
  1958. BUGS
  1959.  
  1960.  
  1961. SEE ALSO
  1962.       iniOpenDefault(), iniOpenFile(), iniOpenFromFH(), iniClose(),
  1963.       iniSaveFile(), iniSaveToFH(), <libraries/ini_lib.h>
  1964.  
  1965.  
  1966. ini.library/iniPutByteA
  1967.  
  1968. NAME
  1969.        iniPutByteA -- writes an (U)BYTE array into an context item array.
  1970.  
  1971.  
  1972. SYNOPSIS
  1973.        success = iniPutByteA( ContextStr, ContextItemLine, Array, Entries,
  1974.        D0                     A0          A1               A2     D0
  1975.                               Format, Len, ZeroSep );
  1976.                               D1      D2   D3:8
  1977.  
  1978.        BOOL iniPutByteA( struct iniContext *, struct iniContextItemLine *,
  1979.            BYTE *, ULONG, ULONG, ULONG, UBYTE );
  1980.  
  1981.  
  1982. FUNCTION
  1983.        Writes the values of the given (U)BYTE table to the specified context
  1984.        item array.
  1985.  
  1986.  
  1987. INPUTS
  1988.        ContextStr - The context structure where context line should be put
  1989.        ContextItemLine - The context item line where the array is
  1990.        Array - An (U)BYTE array where to take the values from
  1991.        Entries - Number of entries to write
  1992.        Format - Format of array entries to write out:
  1993.            INI_FORMAT_DEC - Use decimal with no precedor
  1994.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  1995.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  1996.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  1997.            INI_FORMAT_BIN - Use binary with % precedor
  1998.            INI_FORMAT_OCT - Use octal with & precedor
  1999.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  2000.            INI_FORMAT_YN - Use N for zero, Y for all others
  2001.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  2002.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  2003.            INI_UNSIGNED - Add this to indicate unsigned integer
  2004.        Len - Forced length of outputted string or NULL for no force.
  2005.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  2006.  
  2007.  
  2008. RESULT
  2009.        success - TRUE if line could be written else FALSE
  2010.  
  2011.  
  2012. EXAMPLE
  2013.  
  2014.  
  2015. NOTES
  2016.        This function is currently relatively slow. Especially with
  2017.        arrays with more than 16 entries.
  2018.  
  2019.  
  2020. BUGS
  2021.  
  2022.  
  2023. SEE ALSO
  2024.        iniPutWordA(), iniPutLongA(), iniWriteByteA(), iniGetByteA(),
  2025.        <libraries/ini_lib.h>
  2026.  
  2027.  
  2028. ini.library/iniPutFloat
  2029.  
  2030. NAME
  2031.        iniPutFloat -- Puts a quick floating point value into given item line
  2032.  
  2033.  
  2034. SYNOPSIS
  2035.        success = iniPutFloat( ContextStr, ContextItemLine, Value,
  2036.        D0                     A0          A1               D0
  2037.                               Format, Len, ZeroSep );
  2038.                               D1      D2   D3:8
  2039.  
  2040.        BOOL iniPutFloat( struct iniContext *, struct iniContextItemLine *,
  2041.            LONG, ULONG, UBYTE );
  2042.  
  2043.  
  2044. FUNCTION
  2045.        Writes a quick float value into the given context item line
  2046.  
  2047.  
  2048. INPUTS
  2049.        ContextStr - Context structure where quick float value should be put
  2050.        ContextItemLine - Context item line where to store quick float
  2051.        Value - Value to be written
  2052.        FltFormat - Format of the floating point value. Can be any of:
  2053.            INI_FLOAT_FORMAT_DEC - Use decimal with point separator
  2054.            INI_FLOAT_UNSIGNED - Add this to indicate unsigned quick float
  2055.        IntLen - Forced length of integer part or NULL for no force.
  2056.        FracLen - Forced length of fractional part or NULL for no force.
  2057.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  2058.  
  2059.  
  2060. RESULT
  2061.        success - TRUE if successful write else FALSE
  2062.  
  2063.  
  2064. EXAMPLE
  2065.  
  2066.  
  2067. NOTES
  2068.        This function is called from iniWriteFloat().
  2069.  
  2070.  
  2071. BUGS
  2072.  
  2073.  
  2074. SEE ALSO
  2075.        iniPutLong(), iniPutStr(), iniPutFloatA(), iniGetFloat(),
  2076.        iniWriteFloat(), iniReadFloat(), <libraries/ini_lib.h>
  2077.  
  2078.  
  2079. ini.library/iniPutFloatA
  2080.  
  2081. NAME
  2082.        iniPutFloatA -- Puts quick floating point value(s) into item line(s)
  2083.  
  2084.  
  2085. SYNOPSIS
  2086.        success = iniPutFloatA( ContextStr, ContextItemLine, Array, Entries,
  2087.        D0                      A0          A1               A2     D0
  2088.                                FltFormat, IntLen, FracLen, ZeroSep );
  2089.                                D1         D2      D3       D4:8
  2090.  
  2091.        BOOL iniPutFloatA( struct iniContext *, struct iniContextItemLine *,
  2092.            LONG *, ULONG, ULONG, ULONG, ULONG, UBYTE );
  2093.  
  2094.  
  2095. FUNCTION
  2096.        Writes one or more quick float value(s) from an array into the given
  2097.        context item line
  2098.  
  2099.  
  2100. INPUTS
  2101.        ContextStr - Context structure where quick float values should be put
  2102.        ContextItemLine - Context item line where to store quick floats
  2103.        Array - The array where to take the quick float values from
  2104.        Entries - Number of array entries. If the array in the INI file is
  2105.             bigger, the remaining entries will be ignored.
  2106.        FltFormat - Format of the floating point value. Can be any of:
  2107.            INI_FLOAT_FORMAT_DEC - Use decimal with point separator
  2108.            INI_FLOAT_UNSIGNED - Add this to indicate unsigned quick float
  2109.        IntLen - Forced length of integer part or NULL for no force.
  2110.        FracLen - Forced length of fractional part or NULL for no force.
  2111.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  2112.  
  2113.  
  2114. RESULT
  2115.        success - TRUE if accessing was successful else NULL.
  2116.  
  2117.  
  2118. EXAMPLE
  2119.  
  2120.  
  2121. NOTES
  2122.        This function is called from iniWriteFloatA().
  2123.        This function is currently relatively slow. Especially with
  2124.        arrays with more than 16 entries.
  2125.  
  2126.  
  2127. BUGS
  2128.  
  2129.  
  2130. SEE ALSO
  2131.        iniPutLongA(), iniPutStrA(), iniPutFloat(), iniGetFloatA(),
  2132.        iniWriteFloatA(), iniReadFloatA(), <libraries/ini_lib.h>
  2133.  
  2134.  
  2135. ini.library/iniPutLong
  2136.  
  2137. NAME
  2138.        iniPutLong -- Puts a long integer value into the context item line
  2139.  
  2140.  
  2141. SYNOPSIS
  2142.        success = iniPutLong( ContextStr, ContextItemLine, Value, Format,
  2143.        D0                    A0          A1               D0     D1
  2144.                              Len, ZeroSep );
  2145.                              D2   D3:8
  2146.  
  2147.        BOOL iniPutLong( struct iniContext *, struct iniContextItemLine *,
  2148.            LONG, ULONG, ULONG, UBYTE );
  2149.  
  2150.  
  2151. FUNCTION
  2152.        Writes a long integer value into the given context item line
  2153.  
  2154.  
  2155. INPUTS
  2156.        ContextStr - Context structure where the long integers should be put
  2157.        ContextItemLine - Context item line where to store long integer
  2158.        Value - Value to be written
  2159.        Format - Format of the outputted string. Can be any of:
  2160.            INI_FORMAT_DEC - Use decimal with no precedor
  2161.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  2162.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  2163.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  2164.            INI_FORMAT_BIN - Use binary with % precedor
  2165.            INI_FORMAT_OCT - Use octal with & precedor
  2166.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  2167.            INI_FORMAT_YN - Use N for zero, Y for all others
  2168.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  2169.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  2170.            INI_UNSIGNED - Add this to indicate unsigned integer
  2171.        Len - Forced length of outputted string or NULL for no force.
  2172.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  2173.  
  2174.  
  2175. RESULT
  2176.        success - TRUE if value could successfully be written or FALSE
  2177.  
  2178.  
  2179. EXAMPLE
  2180.  
  2181.  
  2182. NOTES
  2183.        This function is called from iniWriteLong().
  2184.  
  2185.  
  2186. BUGS
  2187.  
  2188.  
  2189. SEE ALSO
  2190.        iniPutFloat(), iniPutStr(), iniPutLongA(), iniGetLong(),
  2191.        iniWriteLong(), iniReadLong(), <libraries/ini_lib.h>
  2192.  
  2193.  
  2194. ini.library/iniPutLongA
  2195.  
  2196. NAME
  2197.        iniPutLongA -- Puts long integer value(s) into context item line(s)
  2198.  
  2199.  
  2200. SYNOPSIS
  2201.        success = iniPutLongA( ContextStr, ContextItemLine, Array, Entries,
  2202.        D0                     A0          A1               A2     D0
  2203.                               Format, Len, ZeroSep );
  2204.                               D1      D2   D3:8
  2205.  
  2206.        BOOL iniPutLongA( struct iniContext *, struct iniContextItemLine *,
  2207.            LONG *, ULONG, ULONG, ULONG, UBYTE );
  2208.  
  2209.  
  2210. FUNCTION
  2211.        Writes one or more long integer value(s) from the given array into
  2212.        the specified context item line(s).
  2213.  
  2214.  
  2215. INPUTS
  2216.        ContextStr - Context structure where the long integers should be put
  2217.        ContextItemLine - Context item line where to store long integers
  2218.        Array - The array where to take the long integer values from
  2219.        Entries - Number of array entries.
  2220.        Format - Format of the outputted string. Can be any of:
  2221.            INI_FORMAT_DEC - Use decimal with no precedor
  2222.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  2223.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  2224.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  2225.            INI_FORMAT_BIN - Use binary with % precedor
  2226.            INI_FORMAT_OCT - Use octal with & precedor
  2227.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  2228.            INI_FORMAT_YN - Use N for zero, Y for all others
  2229.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  2230.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  2231.            INI_UNSIGNED - Add this to indicate unsigned integer
  2232.        Len - Forced length of outputted string or NULL for no force.
  2233.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  2234.  
  2235.  
  2236. RESULT
  2237.        success - TRUE if accessing was successful else NULL.
  2238.  
  2239.  
  2240. EXAMPLE
  2241.  
  2242.  
  2243. NOTES
  2244.        This function is called from iniWriteLongA().
  2245.        This function is currently relatively slow. Especially with
  2246.        arrays with more than 16 entries.
  2247.  
  2248.  
  2249. BUGS
  2250.  
  2251.  
  2252. SEE ALSO
  2253.        iniPutFloatA(), iniPutStrA(), iniPutLong(), iniGetLongA(),
  2254.        iniWriteLongA(), iniReadLongA(), <libraries/ini_lib.h>
  2255.  
  2256.  
  2257. ini.library/iniPutStr
  2258.  
  2259. NAME
  2260.        iniPutStr -- Puts a string into context item line
  2261.  
  2262.  
  2263. SYNOPSIS
  2264.        success = iniPutStr( ContextStr, ContextItemLine, String );
  2265.        D0                   A0          A1               A2
  2266.  
  2267.        BOOL iniPutStr( struct iniContext *, struct iniContextItemLine *,
  2268.            STRPTR );
  2269.  
  2270.  
  2271. FUNCTION
  2272.        Writes a string into the given context item line.
  2273.  
  2274.  
  2275. INPUTS
  2276.        ContextStr - Context structure where string should be put
  2277.        ContextItemLine - Context item line where to store string
  2278.        String - String to be written
  2279.  
  2280.  
  2281. RESULT
  2282.        success - TRUE if writing was successful else FALSE
  2283.  
  2284.  
  2285. EXAMPLE
  2286.  
  2287.  
  2288. NOTES
  2289.        This function is called from iniReadStr().
  2290.  
  2291.  
  2292. BUGS
  2293.  
  2294.  
  2295. SEE ALSO
  2296.        iniPutLongA(), iniPutFloatA(), iniPutStr(), iniGetStr(),
  2297.        iniWriteStrA(), iniReadStrA(), <libraries/ini_lib.h>
  2298.  
  2299.  
  2300. ini.library/iniPutStrA
  2301.  
  2302. NAME
  2303.        iniPutStrA -- Stores array(s) of string into the context item line(s)
  2304.  
  2305.  
  2306. SYNOPSIS
  2307.        success = iniPutStrA( ContextStr, ContextItemLine, Array, Entries );
  2308.        D0                    A0          A1               A2     D0
  2309.  
  2310.        BOOL iniPutStrA( struct iniContext *, struct iniContextItemLine *,
  2311.            STRPTR *, ULONG );
  2312.  
  2313.  
  2314. FUNCTION
  2315.        Writes one or more strings into the given context item line from an
  2316.        specified array.
  2317.  
  2318.  
  2319. INPUTS
  2320.        ContextStr - Context structure where strings should be put
  2321.        ContextItemLine - Context item line where to store strings
  2322.        Array - The array where to take the pointers to the strings from
  2323.        Entries - Number of array entries. If the array in the INI file is
  2324.             bigger, the remaining entries will be ignored.
  2325.  
  2326.  
  2327. RESULT
  2328.        success - TRUE if accessing was successful else NULL.
  2329.  
  2330.  
  2331. EXAMPLE
  2332.  
  2333.  
  2334. NOTES
  2335.        This function is called from iniWriteStrA().
  2336.  
  2337.  
  2338. BUGS
  2339.  
  2340.  
  2341. SEE ALSO
  2342.        iniPutLongA(), iniPutFloatA(), iniPutStr(), iniGetStrA(),
  2343.        iniWriteStrA(), iniReadStrA(), <libraries/ini_lib.h>
  2344.  
  2345.  
  2346. ini.library/iniPutWordA
  2347.  
  2348. NAME
  2349.        iniPutWordA -- writes a (U)WORD array into a context item array.
  2350.  
  2351.  
  2352. SYNOPSIS
  2353.        success = iniPutWordA( ContextStr, ContextItemLine, Array, Entries,
  2354.        D0                     A0          A1               A2     D0
  2355.                               Format, Len, ZeroSep );
  2356.                               D1      D2   D3:8
  2357.  
  2358.        BOOL iniPutWordA( struct iniContext *, struct iniContextItemLine *,
  2359.            WORD *, ULONG, ULONG, ULONG, UBYTE );
  2360.  
  2361.  
  2362. FUNCTION
  2363.        Writes a context item array and stores the write words from a
  2364.        (U)WORD table you specified.
  2365.  
  2366.  
  2367. INPUTS
  2368.        ContextStr - The context structure where the context line is in
  2369.        ContextItemLine - The context item line where the array is
  2370.        Array - An (U)WORD array where to store the values
  2371.        Entries - Number of entries to read (further entries will be ignored)
  2372.        Format - Format of the outputted string. Can be any of:
  2373.            INI_FORMAT_DEC - Use decimal with no precedor
  2374.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  2375.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  2376.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  2377.            INI_FORMAT_BIN - Use binary with % precedor
  2378.            INI_FORMAT_OCT - Use octal with & precedor
  2379.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  2380.            INI_FORMAT_YN - Use N for zero, Y for all others
  2381.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  2382.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  2383.            INI_UNSIGNED - Add this to indicate unsigned integer
  2384.        Len - Forced length of outputted string or NULL for no force.
  2385.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  2386.  
  2387.  
  2388. RESULT
  2389.  
  2390.  
  2391. EXAMPLE
  2392.  
  2393.  
  2394. NOTES
  2395.        This function is currently relatively slow. Especially with
  2396.        arrays with more than 16 entries.
  2397.  
  2398.  
  2399. BUGS
  2400.  
  2401.  
  2402. SEE ALSO
  2403.        iniPutByteA(), iniPutLongA(), iniWriteWordA(), iniReadWordA(),
  2404.        <libraries/ini_lib.h>
  2405.  
  2406.  
  2407. ini.library/iniReadByteA
  2408.  
  2409. NAME
  2410.        iniReadByteA -- reads a context item array into a (U)BYTE array.
  2411.  
  2412.  
  2413. SYNOPSIS
  2414.        success = iniReadByteA( iniFile, ContextName, ItemName, Array,
  2415.        D0                      A0       A1           A2        A3
  2416.                                Entries, Flags );
  2417.                                D0       D1
  2418.  
  2419.        BOOL iniReadByteA( struct iniFile *, STRPTR, STRPTR, BYTE *,
  2420.            ULONG, ULONG );
  2421.  
  2422.  
  2423. FUNCTION
  2424.        Searches a context item in a context you specified by name and stores
  2425.        the read bytes into a (U)BYTE table you specified.
  2426.  
  2427.  
  2428. INPUTS
  2429.        iniFile - INI file to be evaluated
  2430.        ContextName - Name of the context where context item is
  2431.        ItemName - Name of the context item to be searched
  2432.        Array - An (U)BYTE array where to store the values
  2433.        Entries - Number of entries to read (further entries will be ignored)
  2434.        Flags - Search flags. They're currently defined as:
  2435.            INIF_ContextCase - Set this flag if the search of the context
  2436.                name should be case sensitive.
  2437.            INIF_ContextItemCase - Set this flag if the search of the context
  2438.                item name should be case sensitive.
  2439.  
  2440.  
  2441. RESULT
  2442.        success - TRUE if line could be evaluated else FALSE
  2443.  
  2444.  
  2445. EXAMPLE
  2446.  
  2447.  
  2448. NOTES
  2449.        Make sure that the given array is big enough to hold all values or
  2450.        some memory area may be overwritten.
  2451.  
  2452.        Fields which can't be evaluated are left unchanged.
  2453.  
  2454.  
  2455. BUGS
  2456.  
  2457.  
  2458. SEE ALSO
  2459.        iniReadWordA(), iniReadLongA(), iniGetByteA(), iniWriteByteA(),
  2460.        <libraries/ini_lib.h>
  2461.  
  2462.  
  2463. ini.library/iniReadFloat
  2464.  
  2465. NAME
  2466.        iniReadFloat -- Reads a quick floating point value
  2467.  
  2468.  
  2469. SYNOPSIS
  2470.        QFloatValue = iniReadFloat( iniFile, ContextName, ItemName, Default,
  2471.        D0                          A0       A1           A2        D0
  2472.                                    Flags );
  2473.                                    D1
  2474.  
  2475.        LONG iniReadFloat( struct iniFile *, STRPTR, STRPTR, LONG, ULONG );
  2476.  
  2477.  
  2478. FUNCTION
  2479.        Searches the INI file for the desired context and the desired context
  2480.        items and returns its quick floating point value.
  2481.  
  2482.  
  2483. INPUTS
  2484.        
  2485.        iniFile - INI file to be evaluated
  2486.        ContextName - Name of the context where context item is
  2487.        ItemName - Name of the context item to be searched
  2488.        Default - Default value to take if contents could not be evaluated
  2489.        Flags - Search flags. They're currently defined as:
  2490.            INIF_ContextCase - Set this flag if the search of the context
  2491.                name should be case sensitive.
  2492.            INIF_ContextItemCase - Set this flag if the search of the context
  2493.                item name should be case sensitive.
  2494.  
  2495.  
  2496. RESULT
  2497.        QFloatValue - The quick float value extracted out
  2498.  
  2499.  
  2500. EXAMPLE
  2501.  
  2502.  
  2503. NOTES
  2504.        Only the first four fractional digits are evaluated. However, the
  2505.        5th digit is evaluated for rounding purposes.
  2506.  
  2507.  
  2508. BUGS
  2509.  
  2510.  
  2511. SEE ALSO
  2512.        iniReadLong(), iniReadStr(), iniReadFloatA(), iniWriteFloat(),
  2513.        GetFloat(), iniPutFloat(), <libraries/ini_lib.h>
  2514.  
  2515.  
  2516. ini.library/iniReadFloatA
  2517.  
  2518. NAME
  2519.        iniReadFloatA -- Reads quick floating point value(s) into an array
  2520.  
  2521.  
  2522. SYNOPSIS
  2523.        success = iniReadFloatA( iniFile, ContextName, ItemName, Array,
  2524.        D0                       A0       A1           A2        D0
  2525.                                 Entries, Flags );
  2526.                                 D1       D2
  2527.  
  2528.        BOOL iniReadFloatA( struct iniFile *, STRPTR, STRPTR, LONG *,
  2529.            ULONG, ULONG );
  2530.  
  2531.  
  2532. FUNCTION
  2533.        Searches the context given for the string given in context item and
  2534.        reads one or more quick float value(s) and stores them into the
  2535.        specified array.
  2536.  
  2537.  
  2538. INPUTS
  2539.        iniFile - INI file to be evaluated
  2540.        ContextName - Name of the context where context item is
  2541.        ItemName - Name of the context item to be searched
  2542.        Default - Default value to take if contents could not be evaluated
  2543.        Flags - Search flags. They're currently defined as:
  2544.            INIF_ContextCase - Set this flag if the search of the context
  2545.                name should be case sensitive.
  2546.            INIF_ContextItemCase - Set this flag if the search of the context
  2547.                item name should be case sensitive.
  2548.  
  2549.  
  2550. RESULT
  2551.        success - TRUE if accessing was successful else NULL.
  2552.  
  2553.  
  2554. EXAMPLE
  2555.  
  2556.  
  2557. NOTES
  2558.        This function is currently relatively slow. Especially with
  2559.        arrays with more than 16 entries.
  2560.        Only the first four fractional digits are evaluated. However, the
  2561.        5th digit is evaluated for rounding purposes.
  2562.        Array fields which can't be evaluated (e.g. bad syntax) are left
  2563.        unchanged. So it's good to fill the array with default values first.
  2564.  
  2565.  
  2566. BUGS
  2567.  
  2568.  
  2569. SEE ALSO
  2570.        iniWriteLongA(), iniWriteStrA(), iniReadFloat(), iniWriteFloatA(),
  2571.        iniGetFloatA(), iniPutFloatA(), <libraries/ini_lib.h>
  2572.  
  2573.  
  2574. ini.library/iniReadLong
  2575.  
  2576. NAME
  2577.        iniReadLong -- Reads a long integer value
  2578.  
  2579.  
  2580. SYNOPSIS
  2581.        LongValue = iniReadLong( iniFile, ContextName, ItemName, Default,
  2582.        D0                       A0       A1           A2        D0
  2583.                                 Flags );
  2584.                                 D1
  2585.  
  2586.        LONG iniReadLong( struct iniFile *, STRPTR, STRPTR, LONG, ULONG );
  2587.  
  2588.  
  2589. FUNCTION
  2590.        Searches the INI file for the desired context and the desired context
  2591.        items and returns its long integer value.
  2592.  
  2593.  
  2594. INPUTS
  2595.        
  2596.        iniFile - INI file to be evaluated
  2597.        ContextName - Name of the context where context item is
  2598.        ItemName - Name of the context item to be searched
  2599.        Default - Default value to take if contents could not be evaluated
  2600.        Flags - Search flags. They're currently defined as:
  2601.            INIF_ContextCase - Set this flag if the search of the context
  2602.                name should be case sensitive.
  2603.            INIF_ContextItemCase - Set this flag if the search of the context
  2604.                item name should be case sensitive.
  2605.  
  2606.  
  2607. RESULT
  2608.        LongValue - The long integer extracted out
  2609.  
  2610.  
  2611. EXAMPLE
  2612.  
  2613.  
  2614. NOTES
  2615.  
  2616.  
  2617. BUGS
  2618.  
  2619.  
  2620. SEE ALSO
  2621.        iniReadLong(), iniReadStr(), iniReadFloatA(), iniWriteFloat(),
  2622.        iniGetFloat(), iniPutFloat(), <libraries/ini_lib.h>
  2623.  
  2624.  
  2625. ini.library/iniReadLongA
  2626.  
  2627. NAME
  2628.        iniReadLongA -- Reads long integer value(s) into an array
  2629.  
  2630.  
  2631. SYNOPSIS
  2632.        success = iniReadLongA( iniFile, ContextName, ItemName, Array,
  2633.        D0                      A0          A1        A2        D0
  2634.                                Entries, Flags );
  2635.  
  2636.        BOOL iniReadLongA( struct iniFile *, STRPTR, STRPTR, LONG *,
  2637.            LONG, ULONG );
  2638.  
  2639.  
  2640. FUNCTION
  2641.        Searches the context given for the string given in context item and
  2642.        reads one or more long integer value(s) and stores them into the
  2643.        specified array.
  2644.  
  2645.  
  2646. INPUTS
  2647.        iniFile - INI file to be evaluated
  2648.        ContextName - Name of the context where context item is
  2649.        ItemName - Name of the context item to be searched
  2650.        Default - Default value to take if contents could not be evaluated
  2651.        Flags - Search flags. They're currently defined as:
  2652.            INIF_ContextCase - Set this flag if the search of the context
  2653.                name should be case sensitive.
  2654.            INIF_ContextItemCase - Set this flag if the search of the context
  2655.                item name should be case sensitive.
  2656.  
  2657.  
  2658. RESULT
  2659.        success - TRUE if accessing was successful else NULL.
  2660.  
  2661.  
  2662. EXAMPLE
  2663.  
  2664.  
  2665. NOTES
  2666.        Array fields which can't be evaluated (e.g. bad syntax) are left
  2667.        unchanged. So it's good to fill the array with default values first.
  2668.  
  2669.  
  2670. BUGS
  2671.  
  2672.  
  2673. SEE ALSO
  2674.        iniPutLongA(), iniPutStrA(), iniGetFloat(), iniPutFloatA(),
  2675.        iniReadFloatA(), iniWriteFloatA(), <libraries/ini_lib.h>
  2676.  
  2677.  
  2678. ini.library/iniReadStr
  2679.  
  2680. NAME
  2681.        iniReadStr -- Gets a string
  2682.  
  2683.  
  2684. SYNOPSIS
  2685.        String = iniReadStr( iniFile, ContextName, ItemName, Default,
  2686.        D0                   A0       A1           A2        A3
  2687.                             Flags );
  2688.                             D0
  2689.  
  2690.        STRPTR iniReadStr( struct iniFile *, STRPTR, STRPTR, STRPTR, ULONG );
  2691.  
  2692.  
  2693. FUNCTION
  2694.        Searches the given context item in the given context and returns, if
  2695.        found the context item data as a string.
  2696.  
  2697.  
  2698. INPUTS
  2699.        iniFile - INI file to be evaluated
  2700.        ContextName - Name of the context where context item is
  2701.        ItemName - Name of the context item to be searched
  2702.        Default - Default string to take if contents could not be evaluated
  2703.        Flags - Search flags. They're currently defined as:
  2704.            INIF_ContextCase - Set this flag if the search of the context
  2705.                name should be case sensitive.
  2706.            INIF_ContextItemCase - Set this flag if the search of the context
  2707.                item name should be case sensitive.
  2708.  
  2709.  
  2710. RESULT
  2711.        String - The string value extracted out
  2712.  
  2713.  
  2714. EXAMPLE
  2715.  
  2716.  
  2717. NOTES
  2718.        The string returned must be deallocated with iniFreeNameStr() after
  2719.        use.
  2720.  
  2721.  
  2722. BUGS
  2723.  
  2724.  
  2725. SEE ALSO
  2726.        iniReadLongA(), iniReadFloatA(), iniWriteStr(), iniGetStrA(),
  2727.        iniPutStrA(), <libraries/ini_lib.h>
  2728.  
  2729.  
  2730. ini.library/iniReadStrA
  2731.  
  2732. NAME
  2733.        iniReadStrA -- Extracts strings out of an array
  2734.  
  2735.  
  2736. SYNOPSIS
  2737.        success = iniReadStrA( iniFile, ContextName, ItemName, Array,
  2738.        D0                     A0       A1           A2        A3
  2739.                               Entries, Flags );
  2740.                               D0       D1
  2741.  
  2742.        BOOL iniReadStrA( struct iniFile *, STRPTR, STRPTR, STRPTR *, ULONG,
  2743.            ULONG );
  2744.  
  2745.  
  2746. FUNCTION
  2747.        Searches for the given context item in the given context and reads
  2748.        the string(s) into the specified array.
  2749.  
  2750.  
  2751. INPUTS
  2752.        iniFile - INI file to be evaluated
  2753.        ContextName - Name of the context where context item is
  2754.        ItemName - Name of the context item to be searched
  2755.        Array - Array where to put the pointers to the strings
  2756.        Flags - Search flags. They're currently defined as:
  2757.            INIF_ContextCase - Set this flag if the search of the context
  2758.                name should be case sensitive.
  2759.            INIF_ContextItemCase - Set this flag if the search of the context
  2760.                item name should be case sensitive.
  2761.  
  2762.  
  2763. RESULT
  2764.        success - TRUE if accessing was successful else NULL.
  2765.  
  2766.  
  2767. EXAMPLE
  2768.  
  2769.  
  2770. NOTES
  2771.        Array fields which can't be evaluated (e.g. bad syntax) are left
  2772.        unchanged. So it's good to fill the array with default strings first.
  2773.        All array fields must be deallocated with iniFreeNameStr() when they
  2774.        are not required anymore. This means that the default entries of the
  2775.        array must be iniAllocNameStr() strings!
  2776.  
  2777. BUGS
  2778.  
  2779.  
  2780. SEE ALSO
  2781.        iniReadLongA(), iniReadFloatA(), iniReadStr(), iniWriteStrA(),
  2782.        iniGetStrA(), iniPutStrA(), <libraries/ini_lib.h>
  2783.  
  2784.  
  2785. ini.library/iniReadWordA
  2786.  
  2787. NAME
  2788.        iniReadWordA -- reads a context item array into a (U)WORD array.
  2789.  
  2790.  
  2791. SYNOPSIS
  2792.        success = iniReadWordA( iniFile, ContextName, ItemName, Array,
  2793.        D0                      A0       A1           A2        A3
  2794.                                Entries, Flags );
  2795.                                D0       D1
  2796.  
  2797.        BOOL iniReadWordA( struct iniFile *, STRPTR, STRPTR, WORD *,
  2798.            ULONG, ULONG );
  2799.  
  2800.  
  2801. FUNCTION
  2802.        Searches a context item in a context you specified by name and stores
  2803.        the read bytes into a (U)WORD table you specified.
  2804.  
  2805.  
  2806. INPUTS
  2807.        iniFile - INI file to be evaluated
  2808.        ContextName - Name of the context where context item is
  2809.        ItemName - Name of the context item to be searched
  2810.        Array - An (U)WORD array where to store the values
  2811.        Entries - Number of entries to read (further entries will be ignored)
  2812.        Flags - Search flags. They're currently defined as:
  2813.            INIF_ContextCase - Set this flag if the search of the context
  2814.                name should be case sensitive.
  2815.            INIF_ContextItemCase - Set this flag if the search of the context
  2816.                item name should be case sensitive.
  2817.  
  2818.  
  2819. RESULT
  2820.        success - TRUE if line could be evaluated else FALSE
  2821.  
  2822.  
  2823. EXAMPLE
  2824.  
  2825.  
  2826. NOTES
  2827.        Make sure that the given array is big enough to hold all values or
  2828.        some memory area may be overwritten.
  2829.  
  2830.        Fields which can't be evaluated are left unchanged.
  2831.  
  2832.  
  2833. BUGS
  2834.  
  2835.  
  2836. SEE ALSO
  2837.        iniReadByteA(), iniReadLongA(), iniGetWordA(), iniWriteWordA(),
  2838.        <libraries/ini_lib.h>
  2839.  
  2840.  
  2841. ini.library/iniRemContext
  2842.  
  2843. NAME
  2844.        iniRemContext -- removes the last context from an INI file structure
  2845.  
  2846.  
  2847. SYNOPSIS
  2848.        iniRemContext( iniFile );
  2849.                       A0
  2850.  
  2851.        void iniRemContext( struct iniFile *);
  2852.  
  2853.  
  2854. FUNCTION
  2855.        Removes a previously generated and added context from a specified
  2856.        INI file structure. The entry removed is the last one.
  2857.  
  2858.  
  2859. INPUTS
  2860.        iniFile - Pointer to INI structure where to remove from
  2861.  
  2862.  
  2863. EXAMPLE
  2864.  
  2865.  
  2866. NOTES
  2867.        This function *DOESN'T* do any deallocations. It just removes the
  2868.        node from the context list.
  2869.  
  2870.  
  2871. BUGS
  2872.  
  2873.  
  2874. SEE ALSO
  2875.        iniCreateContext(), iniFreeContext(), iniAddContext(),
  2876.        iniInsertContext(), iniDeleteContext(), <libraries/ini_lib.h>
  2877.  
  2878.  
  2879. ini.library/iniRemContextItem
  2880.  
  2881. NAME
  2882.        iniRemContextItem -- removes the last context item line from a
  2883.                             context structure
  2884.  
  2885.  
  2886. SYNOPSIS
  2887.        iniRemContextItem( ContextStr );
  2888.                           A0
  2889.  
  2890.        void iniRemContextItem( struct iniContext *);
  2891.  
  2892.  
  2893. FUNCTION
  2894.        Removes a previously generated context item line from a context
  2895.        structure. The context item line removed is the last one.
  2896.  
  2897.  
  2898. INPUTS
  2899.        ContextStr - Pointer to context structure where to remove from
  2900.  
  2901.  
  2902. EXAMPLE
  2903.  
  2904.  
  2905. NOTES
  2906.        This function just removes the node, it *DOESN'T* deallocate any
  2907.        memory.
  2908.  
  2909.  
  2910. BUGS
  2911.  
  2912.  
  2913. SEE ALSO
  2914.        iniCreateContextItem(), iniFreeContextItem(), iniRemContextItem(),
  2915.        iniInsertContextItem(), iniDeleteContextItem(), <libraries/ini_lib.h>
  2916.  
  2917.  
  2918. ini.library/iniSaveFile
  2919.  
  2920. NAME
  2921.        iniSaveFile -- Saves an .INI file from an INI structure to disk
  2922.  
  2923.  
  2924. SYNOPSIS
  2925.        written = iniSaveFile( iniFile, name, accessMode );
  2926.        D0                     A0       D1    D2
  2927.  
  2928.        ULONG iniSaveFile( struct iniFile *, STRPTR, LONG );
  2929.  
  2930.  
  2931. FUNCTION
  2932.        Saves an INI file to disk using the current INI structure. This
  2933.        function usually is called when the user selects 'Save' in an
  2934.        application.
  2935.  
  2936.  
  2937. INPUTS
  2938.        iniFile - INI structure to be saved
  2939.        name - Name of the INI file to be created.
  2940.        accessMode - Write mode of file (see <libraries/dos.h> for details)
  2941.  
  2942.  
  2943. RESULT
  2944.        written - Number of bytes written in total or -1 on error.
  2945.  
  2946.  
  2947. EXAMPLE
  2948.  
  2949.  
  2950. NOTES
  2951.  
  2952.  
  2953. BUGS
  2954.  
  2955.  
  2956. SEE ALSO
  2957.        iniOpen(), iniOpenDefault(), iniOpenFromFH(), iniOpenMem(),
  2958.        iniClose(), <libraries/ini_lib.h>, <libraries/dos.h>
  2959.  
  2960.  
  2961. ini.library/iniSaveToFH
  2962.  
  2963. NAME
  2964.        iniSaveToFH -- Saves an INI structure to an already opened file
  2965.  
  2966.  
  2967. SYNOPSIS
  2968.        written = iniSaveToFH( fh, iniFile );
  2969.        D0                     A0  A1
  2970.  
  2971.        ULONG iniSaveToFH( BPTR, struct iniFile *);
  2972.  
  2973.  
  2974. FUNCTION
  2975.        Writes the INI data from the specified INI structure to the file
  2976.        already opened. The file won't be closed after writing, so you can
  2977.        add more data manually.
  2978.  
  2979.  
  2980. INPUTS
  2981.        fh - BPTR to an file handle of the already opened file to be written.
  2982.        iniFile - INI structure to be saved
  2983.  
  2984.  
  2985. RESULT
  2986.        written - Number of bytes written in total or -1 on error.
  2987.  
  2988.  
  2989. EXAMPLE
  2990.  
  2991.  
  2992. NOTES
  2993.  
  2994.  
  2995. BUGS
  2996.  
  2997.  
  2998. SEE ALSO
  2999.        iniOpenDefault(), iniOpenFile(), iniOpenFromFH(), iniOpenMem(),
  3000.        iniClose(), iniSaveFile(), <libraries/ini_lib.h>
  3001.  
  3002.  
  3003. ini.library/iniSetNameStr
  3004.  
  3005. NAME
  3006.        iniSetNameStr -- sets a name string in a given structure offset
  3007.  
  3008.  
  3009. SYNOPSIS
  3010.        namestring = iniSetNameStr( StructPos, namestring );
  3011.        D0                          A0
  3012.  
  3013.        STRPTR iniSetNameStr( STRPTR *, STRPTR namestring );
  3014.  
  3015.  
  3016. FUNCTION
  3017.        Stores a name string into an structure position. This is required
  3018.        if you use own strings in the library handlers.
  3019.  
  3020.  
  3021. INPUTS
  3022.        StructPos - A memory pointer where the string pointer should be
  3023.            assigned.
  3024.        namestring - The name string to be assigned.
  3025.  
  3026.  
  3027. RESULT
  3028.        namestring - The name string stored or NULL on error. 
  3029.  
  3030.  
  3031. EXAMPLE
  3032.  
  3033.  
  3034. NOTES
  3035.        The namestring is a copy of string, but it's freed via iniFreePMem()
  3036.  
  3037.  
  3038. BUGS
  3039.  
  3040.  
  3041. SEE ALSO
  3042.       iniAllocNameStr(), iniFreeNameStr(), iniSetString()
  3043.  
  3044.  
  3045. ini.library/iniSetString
  3046.  
  3047. NAME
  3048.        iniSetString -- allocates and sets a name string in a given structure
  3049.            offset
  3050.  
  3051.  
  3052. SYNOPSIS
  3053.        namestring = iniSetString( StructPos, string );
  3054.        D0                          A0
  3055.  
  3056.        STRPTR iniSetNameStr( STRPTR *, STRPTR string );
  3057.  
  3058.  
  3059. FUNCTION
  3060.        Allocates a name string out of a standard NULL-terminated C-String
  3061.        and assigns the allocated pointer to the structure position.
  3062.        This is required if you use own strings in the library handlers.
  3063.  
  3064.  
  3065. INPUTS
  3066.        StructPos - A memory pointer where the string pointer should be
  3067.            assigned.
  3068.        string - The C-String to be assigned.
  3069.  
  3070.  
  3071. RESULT
  3072.        namestring - The name string stored or NULL on error. 
  3073.  
  3074.  
  3075. EXAMPLE
  3076.  
  3077.  
  3078. NOTES
  3079.        The namestring is a copy of string, but it's freed via iniFreePMem()
  3080.  
  3081.  
  3082. BUGS
  3083.  
  3084.  
  3085. SEE ALSO
  3086.       iniAllocNameStr(), iniFreeNameStr(), iniSetNameStr()
  3087.  
  3088.  
  3089. ini.library/iniStrToFloat
  3090.  
  3091. NAME
  3092.        iniStrToFloat -- Converts a string to a quick float value.
  3093.  
  3094.  
  3095. SYNOPSIS
  3096.        QFloat = iniStrToFloat( String, Default );
  3097.        D0                      A0      D0
  3098.  
  3099.        LONG iniStrToFloat( STRPTR, LONG );
  3100.  
  3101.  
  3102. FUNCTION
  3103.        This function is used to convert a standard ASCII string to a
  3104.        quick float value. The string may have signs (+/-) and a decimal
  3105.        point. A quick float value has in it's upper 16-bits the decimal
  3106.        value and in the lower 16-bits the fraction. That means, the highest
  3107.        possible accuracy is 1/65536. If the string can't be converted for
  3108.        any reason, the default value is used.
  3109.  
  3110.  
  3111. INPUTS
  3112.        String - The string containing the quick float value.
  3113.        Default - Default quick float value to use if error.
  3114.  
  3115.  
  3116. RESULT
  3117.        QFloat - The converted quick float value or the default value.
  3118.  
  3119.  
  3120. EXAMPLE
  3121.        Calling the function with a string containing 3.14159 will result in
  3122.        QFloat with 3.1416.
  3123.  
  3124.  
  3125. NOTES
  3126.        The string's value may not exceed -65536/+65535 or an overflow error
  3127.        will occur. The value after the period will only be interpreted up
  3128.        to 4 digits. However, the 5th digit will be interpreted for rounding
  3129.        purposes.
  3130.  
  3131.  
  3132. BUGS
  3133.  
  3134.  
  3135. SEE ALSO
  3136.       iniStrToInt(), iniIntToStr(), iniFloatToStr(), <libraries/ini_lib.h>
  3137.  
  3138.  
  3139. ini.library/iniStrToInt
  3140.  
  3141. NAME
  3142.        iniStrToInt -- Converts a string to an (un)signed 32-bit integer.
  3143.  
  3144.  
  3145. SYNOPSIS
  3146.        Integer = iniStrToInt( String, Default );
  3147.        D0                     A0      D0
  3148.  
  3149.        LONG iniStrToInt( STRPTR, LONG );
  3150.  
  3151.  
  3152. FUNCTION
  3153.        This function is used to convert a standard ASCII string to a
  3154.        standard 32-bit (un)signed integer value. The string may have signs
  3155.        (+/-) and can be in hexadecimal, decimal, binary and octal formats.
  3156.        Hexadecimal strings are preceded with $ or 0x. Binary strings with
  3157.        %, octal strings with & and decimal strings start either with nothing
  3158.        or with a #. In addition to this, the following strings will return
  3159.        -1: Yes, Y, True, On
  3160.         0: No, N, False, Off
  3161.  
  3162.        The match isn't case sensitive, so e.g. YES will also return -1.
  3163.        This makes evaluations easier of context items like:
  3164.        EnableFunction = Yes.
  3165.  
  3166.        This means that iniReadLong, etc. automatically take care of this.
  3167.  
  3168. INPUTS
  3169.        String - The string containing the integer value.
  3170.        Default - Default integer value to use if error.
  3171.  
  3172.  
  3173. RESULT
  3174.        Integer - The converted integer value or the default value.
  3175.  
  3176.  
  3177. EXAMPLE
  3178.        A string containing: $0037 will return 55 in Integer,
  3179.        %001110 will return 14, and &17 will result in 15.
  3180.  
  3181.  
  3182. NOTES
  3183.        However, the string's value may not exceed -4,294,967,296 and
  3184.        +4,294,967,295 (32 bit limit) or an overflow error will occur.
  3185.        This function is used for all string to integer conversions.
  3186.  
  3187.  
  3188. BUGS
  3189.  
  3190.  
  3191. SEE ALSO
  3192.       iniStrToFloat(), iniIntToStr(), iniFloatToStr(), <libraries/ini_lib.h>
  3193.  
  3194.  
  3195. ini.library/iniWriteByteA
  3196.  
  3197. NAME
  3198.        iniWriteByteA -- writes an (U)BYTE array into an context item array.
  3199.  
  3200.  
  3201. SYNOPSIS
  3202.        success = iniWriteByteA( iniFile, ContextName, ItemName, Array,
  3203.        D0                       A0       A1           A2        A3
  3204.                                 Entries, Flags, Format, Len, ZeroSep );
  3205.                                 D0       D1     D2      D3   D4:8
  3206.  
  3207.        BOOL iniWriteByteA( struct iniFile *, STRPTR, STRPTR, BYTE *,
  3208.            ULONG, ULONG, ULONG, ULONG, UBYTE );
  3209.  
  3210.  
  3211. FUNCTION
  3212.        Writes the values of the given (U)BYTE table to the specified context
  3213.        item in the given context.
  3214.  
  3215.  
  3216. INPUTS
  3217.        iniFile - INI structure of the INI file which should be affected
  3218.        ContextName - The context name (C-String) in which context to store
  3219.        ItemName - The context item name (C-String) in which the context item
  3220.            lies to write to.
  3221.        Array - An (U)BYTE array where to take the values from
  3222.        Entries - Number of entries to write
  3223.        Flags - Search flags. They're currently defined as:
  3224.            INIF_ContextCase - Set this flag if the search of the context
  3225.                name should be case sensitive.
  3226.            INIF_ContextItemCase - Set this flag if the search of the context
  3227.                item name should be case sensitive.
  3228.        Format - Format of array entries to write out:
  3229.            INI_FORMAT_DEC - Use decimal with no precedor
  3230.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  3231.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  3232.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  3233.            INI_FORMAT_BIN - Use binary with % precedor
  3234.            INI_FORMAT_OCT - Use octal with & precedor
  3235.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  3236.            INI_FORMAT_YN - Use N for zero, Y for all others
  3237.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  3238.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  3239.            INI_UNSIGNED - Add this to indicate unsigned integer
  3240.        Len - Forced length of outputted string or NULL for no force.
  3241.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  3242.  
  3243.  
  3244. RESULT
  3245.        success - TRUE if line could be written else FALSE
  3246.  
  3247.  
  3248. EXAMPLE
  3249.  
  3250.  
  3251. NOTES
  3252.        This function is currently relatively slow. Especially with
  3253.        arrays with more than 16 entries.
  3254.  
  3255.  
  3256. BUGS
  3257.  
  3258.  
  3259. SEE ALSO
  3260.        iniWriteWordA(), iniWriteLongA(), iniPutByteA(), iniReadByteA(),
  3261.        <libraries/ini_lib.h>
  3262.  
  3263.  
  3264. ini.library/iniWriteFloat
  3265.  
  3266. NAME
  3267.        iniWriteFloat -- Writes a quick floating point value into given
  3268.            item line
  3269.  
  3270.  
  3271. SYNOPSIS
  3272.        success = iniWriteFloat( iniFile, ContextName, ItemName, Value,
  3273.        D0                       A0       A1           A2        D0
  3274.                                 Flags, FltFormat, IntLen, FracLen, ZeroSep );
  3275.                                 D1     D2         D3      D4       D5:8
  3276.  
  3277.        BOOL iniWriteFloat( struct iniFile *, STRPTR, STRPTR, LONG, ULONG,
  3278.            ULONG, ULONG, UBYTE );
  3279.  
  3280.  
  3281. FUNCTION
  3282.        Writes a quick float value into the given context item, belonging
  3283.        to the specified context.
  3284.  
  3285.  
  3286. INPUTS
  3287.        iniFile - INI structure of the INI file to be accessed
  3288.        ContextName - Name of the context where context item lies
  3289.        ItemName - Name of the context item where context item line lies
  3290.        Value - Quick float value to be written
  3291.        Flags - Search flags. They're currently defined as:
  3292.            INIF_ContextCase - Set this flag if the search of the context
  3293.                name should be case sensitive.
  3294.            INIF_ContextItemCase - Set this flag if the search of the context
  3295.                item name should be case sensitive.
  3296.        FltFormat - Format of the floating point value. Can be any of:
  3297.            INI_FLOAT_FORMAT_DEC - Use decimal with point separator
  3298.            INI_FLOAT_UNSIGNED - Add this to indicate unsigned quick float
  3299.        IntLen - Forced length of integer part or NULL for no force.
  3300.        FracLen - Forced length of fractional part or NULL for no force.
  3301.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  3302.  
  3303.  
  3304. RESULT
  3305.        success - TRUE if successful write else FALSE
  3306.  
  3307.  
  3308. EXAMPLE
  3309.  
  3310.  
  3311. NOTES
  3312.        This function calls from iniPutFloat().
  3313.  
  3314.  
  3315. BUGS
  3316.  
  3317.  
  3318. SEE ALSO
  3319.        iniWriteLong(), iniWriteStr(), iniWriteFloatA(), iniReadFloat(),
  3320.        iniPutFloat(), iniGetFloat(), <libraries/ini_lib.h>
  3321.  
  3322.  
  3323. ini.library/iniWriteFloatA
  3324.  
  3325. NAME
  3326.        iniWriteFloatA -- Writes quick floating point value(s) into
  3327.            item line(s)
  3328.  
  3329.  
  3330. SYNOPSIS
  3331.        success = iniWriteFloatA( iniFile, ContextName, ItemName, Array,
  3332.        D0                        A0       A1           A2        A3
  3333.                                  Entries, Flags, FltFormat, IntLen, FracLen,
  3334.                                  D0       D1     D2         D3      D4:8
  3335.                                  ZeroSep );
  3336.                                  D5
  3337.  
  3338.        BOOL iniWriteFloatA( struct iniFile *, STRPTR, STRPTR, LONG *,
  3339.            ULONG, ULONG, ULONG, ULONG, ULONG, UBYTE );
  3340.  
  3341.  
  3342. FUNCTION
  3343.        Writes one or more quick float value(s) from an array into the given
  3344.        context item, belonging to the specified context.
  3345.  
  3346.  
  3347. INPUTS
  3348.        iniFile - INI structure where to assign write to
  3349.        ContextName - The name of the context to be affected
  3350.        ItemName - The name of the context item where to write array to
  3351.        Array - The array where to write the quick float values to
  3352.        Entries - Number of array entries. If the array in the INI file is
  3353.             bigger, the remaining entries will be ignored.
  3354.        Flags - Search flags. They're currently defined as:
  3355.            INIF_ContextCase - Set this flag if the search of the context
  3356.                name should be case sensitive.
  3357.            INIF_ContextItemCase - Set this flag if the search of the context
  3358.                item name should be case sensitive.
  3359.        FltFormat - Format of the floating point value. Can be any of:
  3360.            INI_FLOAT_FORMAT_DEC - Use decimal with point separator
  3361.            INI_FLOAT_UNSIGNED - Add this to indicate unsigned quick float
  3362.        IntLen - Forced length of integer part or NULL for no force.
  3363.        FracLen - Forced length of fractional part or NULL for no force.
  3364.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  3365.  
  3366.  
  3367. RESULT
  3368.        success - TRUE if accessing was successful else NULL.
  3369.  
  3370.  
  3371. EXAMPLE
  3372.  
  3373.  
  3374. NOTES
  3375.        This function calls iniPutFloatA().
  3376.        This function is currently relatively slow. Especially with
  3377.        arrays with more than 16 entries.
  3378.  
  3379.  
  3380. BUGS
  3381.  
  3382.  
  3383. SEE ALSO
  3384.        iniWriteLongA(), iniWriteStrA(), iniWriteFloat(), iniReadFloatA(),
  3385.        iniPutFloatA(), iniGetFloatA(), <libraries/ini_lib.h>
  3386.  
  3387.  
  3388. ini.library/iniWriteLong
  3389.  
  3390. NAME
  3391.        iniWriteLong -- Writes a long integer value into the context item line
  3392.  
  3393.  
  3394. SYNOPSIS
  3395.        success = iniWriteLong( iniFile, ContextName, ItemName, Value,
  3396.        D0                      A0       A1           A2        D0
  3397.                                Flags, Format, Len, ZeroSep );
  3398.                                D1     D2      D3   D4:8
  3399.  
  3400.        BOOL iniWriteLong( struct iniFile *, STRPTR, STRPTR, LONG, ULONG,
  3401.            ULONG, UBYTE );
  3402.  
  3403.  
  3404. FUNCTION
  3405.        Writes a long integer value into the specified context item line,
  3406.        belonging to the given context.
  3407.  
  3408.  
  3409. INPUTS
  3410.        iniFile - INI structure of the INI file which should be affected
  3411.        ContextName - Name of the context where the value should be stored
  3412.        ItemName - Name of the context item where to store value to
  3413.        Value - Value to be written
  3414.        Flags - Search flags. They're currently defined as:
  3415.            INIF_ContextCase - Set this flag if the search of the context
  3416.                name should be case sensitive.
  3417.            INIF_ContextItemCase - Set this flag if the search of the context
  3418.                item name should be case sensitive.
  3419.        Format - Format of the outputted string. Can be any of:
  3420.            INI_FORMAT_DEC - Use decimal with no precedor
  3421.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  3422.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  3423.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  3424.            INI_FORMAT_BIN - Use binary with % precedor
  3425.            INI_FORMAT_OCT - Use octal with & precedor
  3426.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  3427.            INI_FORMAT_YN - Use N for zero, Y for all others
  3428.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  3429.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  3430.            INI_UNSIGNED - Add this to indicate unsigned integer
  3431.        Len - Forced length of outputted string or NULL for no force.
  3432.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  3433.  
  3434.  
  3435. RESULT
  3436.        success - TRUE if value could successfully be written or FALSE
  3437.  
  3438.  
  3439. EXAMPLE
  3440.  
  3441.  
  3442. NOTES
  3443.        This function calls iniPutLong().
  3444.  
  3445.  
  3446. BUGS
  3447.  
  3448.  
  3449. SEE ALSO
  3450.        iniWriteFloat(), iniWriteStr(), iniWriteLongA(), iniReadLong(),
  3451.        iniPutLong(), iniGetLong(), <libraries/ini_lib.h>
  3452.  
  3453.  
  3454. ini.library/iniWriteLongA
  3455.  
  3456. NAME
  3457.        iniWriteLongA -- writes an (U)LONG array into an context item array.
  3458.  
  3459.  
  3460. SYNOPSIS
  3461.        success = iniWriteLongA( iniFile, ContextName, ItemName, Array,
  3462.        D0                       A0       A1           A2        A3
  3463.                                 Entries, Flags, Format, Len, ZeroSep );
  3464.                                 D0       D1     D2      D3   D4:8
  3465.  
  3466.        BOOL iniWriteLongA( struct iniFile *, STRPTR, STRPTR, LONG *,
  3467.            ULONG, ULONG, ULONG, ULONG, UBYTE );
  3468.  
  3469.  
  3470. FUNCTION
  3471.        Writes the values of the given (U)LONG table to the specified context
  3472.        item in the given context.
  3473.  
  3474.  
  3475. INPUTS
  3476.        iniFile - INI structure of the INI file which should be affected
  3477.        ContextName - The context name (C-String) in which context to store
  3478.        ItemName - The context item name (C-String) in which the context item
  3479.            lies to write to.
  3480.        Array - An (U)LONG array where to take the values from
  3481.        Entries - Number of entries to write
  3482.        Flags - Search flags. They're currently defined as:
  3483.            INIF_ContextCase - Set this flag if the search of the context
  3484.                name should be case sensitive.
  3485.            INIF_ContextItemCase - Set this flag if the search of the context
  3486.                item name should be case sensitive.
  3487.        Format - Format of array entries to write out:
  3488.            INI_FORMAT_DEC - Use decimal with no precedor
  3489.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  3490.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  3491.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  3492.            INI_FORMAT_BIN - Use binary with % precedor
  3493.            INI_FORMAT_OCT - Use octal with & precedor
  3494.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  3495.            INI_FORMAT_YN - Use N for zero, Y for all others
  3496.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  3497.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  3498.            INI_UNSIGNED - Add this to indicate unsigned integer
  3499.        Len - Forced length of outputted string or NULL for no force.
  3500.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  3501.  
  3502.  
  3503. RESULT
  3504.        success - TRUE if line could be written else FALSE
  3505.  
  3506.  
  3507. EXAMPLE
  3508.  
  3509.  
  3510. NOTES
  3511.        This function is currently relatively slow. Especially with
  3512.        arrays with more than 16 entries.
  3513.  
  3514.  
  3515. BUGS
  3516.  
  3517.  
  3518. SEE ALSO
  3519.        iniWriteByteA(), iniWriteWordA(), iniPutLongA(), iniReadLongA(),
  3520.        <libraries/ini_lib.h>
  3521.  
  3522.  
  3523. ini.library/iniWriteStr
  3524.  
  3525. NAME
  3526.        iniWriteStr -- Writes a string into a context item line
  3527.  
  3528.  
  3529. SYNOPSIS
  3530.        success = iniWriteStr( iniFile, ContextName, ItemName, String,
  3531.        D0                     A0       A1           A2        A3
  3532.                               Flags );
  3533.                               D0
  3534.                               
  3535.  
  3536.        BOOL iniWriteStr( struct iniFile *, STRPTR, STRPTR, STRPTR, ULONG );
  3537.  
  3538.  
  3539. FUNCTION
  3540.        Writes a string into the given context item belonging to the
  3541.        specified context.
  3542.  
  3543.  
  3544. INPUTS
  3545.        iniFile - INI structure of the INI file to be written
  3546.        ContextName - Name of the context where the item lies
  3547.        ItemName - Name of the context item where string should be put
  3548.        String - String to be written
  3549.        Flags - Search flags. They're currently defined as:
  3550.            INIF_ContextCase - Set this flag if the search of the context
  3551.                name should be case sensitive.
  3552.            INIF_ContextItemCase - Set this flag if the search of the context
  3553.                item name should be case sensitive.
  3554.  
  3555.  
  3556. RESULT
  3557.        success - TRUE if writing was successful else FALSE
  3558.  
  3559.  
  3560. EXAMPLE
  3561.  
  3562.  
  3563. NOTES
  3564.        This function is called from iniReadStr().
  3565.  
  3566.  
  3567. BUGS
  3568.  
  3569.  
  3570. SEE ALSO
  3571.        iniWriteLongA(), iniWriteFloatA(), iniWriteStr(), iniReadStr(),
  3572.        iniPutStrA(), iniGetStrA(), <libraries/ini_lib.h>
  3573.  
  3574.  
  3575. ini.library/iniWriteStrA
  3576.  
  3577. NAME
  3578.        iniWriteStrA -- Writes an array of string(s) into the context item
  3579.            line(s)
  3580.  
  3581.  
  3582. SYNOPSIS
  3583.        success = iniWriteStrA( iniFile, ContextName, ItemName, Array,
  3584.        D0                      A0       A1           A2        A3
  3585.                                Entries, Flags );
  3586.                                D0       D1
  3587.  
  3588.        BOOL iniWriteStrA( struct iniFile *, STRPTR, STRPTR, STRPTR *,
  3589.            ULONG, ULONG );
  3590.  
  3591.  
  3592. FUNCTION
  3593.        Writes one or more strings into the given context item line,
  3594.        belonging to the specified context from an given array.
  3595.  
  3596.  
  3597. INPUTS
  3598.        iniFile - INI file structure 
  3599.        ContextName - Name of the context where context item lies
  3600.        ItemName - Name of the context item to be accessed
  3601.        Array - The array where to take the pointers of the strings from
  3602.        Entries - Number of array entries. If the array in the INI file is
  3603.             bigger, the remaining entries will be ignored.
  3604.        Flags - Search flags. They're currently defined as:
  3605.            INIF_ContextCase - Set this flag if the search of the context
  3606.                name should be case sensitive.
  3607.            INIF_ContextItemCase - Set this flag if the search of the context
  3608.                item name should be case sensitive.
  3609.  
  3610.  
  3611. RESULT
  3612.        success - TRUE if accessing was successful else NULL.
  3613.  
  3614.  
  3615. EXAMPLE
  3616.  
  3617.  
  3618. NOTES
  3619.        This function calls iniPutStrA().
  3620.  
  3621.  
  3622. BUGS
  3623.  
  3624.  
  3625. SEE ALSO
  3626.        iniWriteLongA(), iniWriteFloatA(), iniWriteStr(), iniReadStrA(),
  3627.        iniPutStrA(), iniGetStrA(), <libraries/ini_lib.h>
  3628.  
  3629.  
  3630. ini.library/iniWriteWordA
  3631.  
  3632. NAME
  3633.        iniWriteWordA -- writes an (U)WORD array into an context item array.
  3634.  
  3635.  
  3636. SYNOPSIS
  3637.        success = iniWriteWordA( iniFile, ContextName, ItemName, Array,
  3638.        D0                       A0       A1           A2        A3
  3639.                                 Entries, Flags, Format, Len, ZeroSep );
  3640.                                 D0       D1     D2      D3   D4:8
  3641.  
  3642.        BOOL iniWriteWordA( struct iniFile *, STRPTR, STRPTR, WORD *,
  3643.            ULONG, ULONG, ULONG, ULONG, UBYTE );
  3644.  
  3645.  
  3646. FUNCTION
  3647.        Writes the values of the given (U)WORD table to the specified context
  3648.        item in the given context.
  3649.  
  3650.  
  3651. INPUTS
  3652.        iniFile - INI structure of the INI file which should be affected
  3653.        ContextName - The context name (C-String) in which context to store
  3654.        ItemName - The context item name (C-String) in which the context item
  3655.            lies to write to.
  3656.        Array - An (U)WORD array where to take the values from
  3657.        Entries - Number of entries to write
  3658.        Flags - Search flags. They're currently defined as:
  3659.            INIF_ContextCase - Set this flag if the search of the context
  3660.                name should be case sensitive.
  3661.            INIF_ContextItemCase - Set this flag if the search of the context
  3662.                item name should be case sensitive.
  3663.        Format - Format of array entries to write out:
  3664.            INI_FORMAT_DEC - Use decimal with no precedor
  3665.            INI_FORMAT_DEC_CHAR - Use decimal with # precedor
  3666.            INI_FORMAT_HEX - Use hexadecimal with $ precedor
  3667.            INI_FORMAT_HEX_0X - Use hexadecimal with 0x precedor
  3668.            INI_FORMAT_BIN - Use binary with % precedor
  3669.            INI_FORMAT_OCT - Use octal with & precedor
  3670.            INI_FORMAT_YESNO - Use No for zero, Yes for all others
  3671.            INI_FORMAT_YN - Use N for zero, Y for all others
  3672.            INI_FORMAT_TRUEFALSE - Use False for zero, True for all others
  3673.            INI_FORMAT_ONOFF - Use Off for zero, On for all others
  3674.            INI_UNSIGNED - Add this to indicate unsigned integer
  3675.        Len - Forced length of outputted string or NULL for no force.
  3676.        ZeroSep - Zero character for IntLen leading zeroes. Usually " " or "0"
  3677.  
  3678.  
  3679. RESULT
  3680.        success - TRUE if line could be written else FALSE
  3681.  
  3682.  
  3683. EXAMPLE
  3684.  
  3685.  
  3686. NOTES
  3687.        This function is currently relatively slow. Especially with
  3688.        arrays with more than 16 entries.
  3689.  
  3690.  
  3691. BUGS
  3692.  
  3693.  
  3694. SEE ALSO
  3695.        iniWriteByteA(), iniWriteLongA(), iniPutWordA(), iniReadWordA(),
  3696.        <libraries/ini_lib.h>
  3697.  
  3698.  
  3699.